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INTRODUCTIONS 



This book is an anthology of all I have 
written for 68 Micro Uournal since I start- 
ed writing the 05-9 User Notes column in 
February 1983. Some errors in spelling and 
grammar have been removed (I imagine others 
have crept in to take their place.), but I 
forced myself to leave in mistakes that I 
made. The most glaring have footnotes 
pointing out the truth. 

This document was prepared using Water- 
loo Script and a Xerox 9700 Laser Printer. 
This let me add footnotes, figures, boxes, 
and an index to the columns. All the foot- 
notes are additions I made while preparing 
this anthology. The figures and boxes are 



features I wished for when I was preparing 
the original column. The contents are from 
the column, but the presentation is differ- 
ent. 

The people at the University of Roches- 
ter Computing Center deserve special thanks 
for their help with this document. This 
book pushed some of the limits of the sys- 
tem. They were always friendly and help- 
ful . 

The index is an attempt to make the 
helter-skelter arrangement of the columns 
bearable. Each month I write about what 
takes my fancy. Sometimes I write about 
several things. Columns written like that 
don't combine into a cohesive book very 
well. I hope the index will guide you to 
the information you need wherever it hides. 



Introductions 
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COLUMN ONE 



OPENING REMARKS 

This Is the first of what I hope will be a 
long series of columns about OS-9 Level 
Two. I plan on discussing some interesting 
aspect of programming in each column. I 
also intend to use this as a soap box for 
my radical ideas about computing in hopes 
of stirring up some controversy. My comput- 
er was financed largely by teaching comput- 
er science. Please bear with me when I have 
a fit of teaching. 

First, by way of introduction, I work 
as a systems programmer on a variety of 
machines. I teach computer science courses 
at a local technical college, and take com- 
puter science courses at the local univer- 
sity. I worked my way up to my job as a 
systems programmer through years of work on 
payroll, student systems, and other busi- 
ness programming type things - you might 
say I paid my dues. I got started on micro- 
computers by building SWTPC's 6809 computer 
kit. I now own two mongrel computers, one 
small, running only FLEX, and seldom used, 
the other large and frequently used. My 
large computer has a GIMIX DMA disk con- 
troller, and a GIMIX 6809 CPU board, two 
eight inch disk drives. 344K of useful mem- 
ory, and assorted I/O boards. It can run 
OS-9 Level Two or FLEX. 

I have a collection of strong opinions 
about computing in general, and microcom- 
puting in particular. The most relevant 
opinion is that I think the staggering sum 
I spent to buy OS-9 Level Two together with 
languages and utilities was money that 
could not have been better spent though I 
do wish the prices were lower. I think 
everyone should get to watch their computer 
seem to come alive, not just those people 
who are willing to work two jobs and live 
on pasta to save enough money. I belong to 
the school of radicals who believe that 
Basic is bad for your brain. I like Pas- 
cal, but find It a little dull. Assembly 
language is lots of fun, but slow going. I 
am looking forward to getting C; 1t sounds 
promising. 

I think it is practically Immoral to 
force even two people to attempt to use a 
6809 at the same time. The fact that it 
sometimes does a passable job with several 
users is not a sign that there is plenty of 
power for several users. The 6809 only runs 
just so fast. No operating system can make 
it run faster. Digital Equipment Corp. 
seems to think its small VAX is probably a 
good single user machine. I have noticed 
that the Xerox Star Is very slow when it's 
editing. Both of those computers can run 
circles around any 6809 machine (and cost 
far more). Both of them run software writ- 
ten by top quality programmers. The differ- 
ence is that those computers are expected 
to make things as easy as possible for 
their users at any reasonable expense. Peo- 
ple who use and program microcomputers 
don't expect that much out of their 
machines. Our machines are microcomputers. 
We expect them to do the same kinds of 
things other microcomputers do. Our 
machines are small, but they are part of a 
new generation. They can do the work of 
several of last generation's micros. We can 



use that power to give several users the 
same poor service, but I would rather see 
one user well pleased by a computer than 
several somewhat dissatisfied users. 

There is some truly excellent software 
available for the 6809. I would rate Micro- 
ware's Pascal as one of the best Pascals I 
have used on any machine. A lot of features 
are missing from OS-9 Level Two. but what 
Is there is up to the highest standards and 
it should be easy to add most of what's 
missing. From my reading of the manual, 
6asic09 seems to be an excellent language 
(as Basic goes). I own a great deal of 
software for FLEX and OS-9. but I can't 
think of any other programs in that league. 
I am open to suggestions. The challenge Is 
to be at least as good as any similar pro- 
gram on ANY MACHINE. For example, I would 
"love to find an editor that qualifies. My 
life would be much easier if I could run an 
editor comparable to .EMACS. XEDIT, SPF, or 
SED on my micro. DYNACALC seems, from its 
advertisements, to be as good as any of the 
Vislclones, maybe the best of them. I am 
holding a grudge against that program 
because it only supports 3(XX) cells (under 
OS-9 Level Two) That's as good as most 
Vislclones, but I have enough memory for 
much more than that. The chance to be the 
first spread sheet program to support 
almost a megabyte of storage (maybe 30000 
cells) in memory on a micro was only a few 
hundred Instructions away, and they didn't 
do it. I would like to propose some pro- 
gramming challenges to the 6809 community. 

I have used spelling checkers that can 
be asked for a list of suggestions for the 
spelling of a questionable word. The good 
ones will provide synonyms on demand too. 
Doing this at a decent clip, and fitting 
the dictionary on a floppy disk should be 
an Interesting challenge. 

I don't know of any high level language 
for the 6809 that can use more than 64K 
even with restrictions. No. I take that 
back. Microware's Pascal can use a sort of 
virtual storage scheme to deal with more 
than 64K of code, but there is no easy way 
to use more than 64K of data. What I had in 
mind was a language that could make use of 
extended addressing. There are lots of use- 
ful tricks, playing with the DAT. using 
software interrupts cleverly, or simply 
running all procedures (subroutines if you 
like that term better) as FORKed tasks. 
Minicomputers used to be limited to a 64K 
address space. Some of the tricks used to 
fit big programs into them can probably be 
adapted to our problmns. 

A state-of-the-art editor would go a 
long way toward promoting the 6809. As 
basic requirements, such an editor should 
be a screen editor capable of using any 
available memory. It should include the 
ability to edit multiple files of arbitrary 
size without resorting to the "new" or 
"more" kludge. It should include the best 
of Wylbur, EMACS, and the other common edi- 
tors. 

If I seem a little shrill about soft- 
ware, it is because I see my beloved 6809 
machine being squeezed out by the flood of 
high quality microcomputers on the market. 
From my point of view, the best feature of 
the 6809 is its elegant architecture. It is 
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no easy to program that it should be pull- 
ing ahead of the field with a flood of 
Guperb software. I see only a trickle. 



fied section you will know I broke down and 
got a new. faster, better 6809 computer. 



GIMIX-III OS-9 

Ok, now I'll get off the soap box and 
down to business. I am thinking of selling 
both my computers, I positively lust after 
the new GIMIX CPU board and "level Three" 
operating system. If there is another 
microcomputer en the market that does what 
it does, I haven't heard of it. Large com- 
puters such as IBM 370 architecture, and 
large DECS can cause attempts to write into 
"protected storage" or execute invalid 
instructions to fail. Special code is exe- 
cuted whenever a program attempts either of 
these activities. Usually the program that 
did it is stopped. Microcomputers don't do 
that kind of thing. The computer will do 
something (maybe something ridiculous such 
as "halt and catch fire") with any data its 
program counter Is pointed at. This can 
cause a faulty program to go out of control 
in unpredictable ways. There 16 no way for 
the microprocessor to know that It 
shouldn't write into some part of memory. 
If you want you can write your name all 
over the BasicOS interpreter. The results 
of that kind of thing are disastrous, pat — 
ticularly if you are sharing the Interpret- 
er with someone. You just have to make 
very sure programs you write never try to 
execute. or write into anything they 
shouldn't. Of course that is just good pro- 
gramming. 

The new board from GIMIX was designed 
to work with OS-9. It is alleged to support 
protected storage and to prevent Invalid 
operations from being presented to the 
microprocessor. This should prevent any 
program from interfering with any other 
program, even, in many cases. Itself. For 
those of you who try to support several 
users, if you use the new GIMIX hard/ 
software no user should be able to cause 
the system, or another user's program to 
fail. Even people like me who don't share 
time with anyone can gain a lot from this 
kind of safety net. Sometlries when I am 
debugging a program everything just comes 
to a stop and I have to re-boot in order to 
continue. It is even worse when there Is a 
long pause then the disk starts seeking. I 
haven't had any data destroyed that way 
yet, but I worry. This new hardware should 
give everyone who can afford it a lot of 
peace of mind. GIMIX has also been able to 
remove every trace of the operating system 
from each task's address space. Programs 
can be run with up to 64K. The board and 
accompanying software have lots of other 
features, but the other one that excites me 
a lot is the memory-to-memory DMA. A lot of 
time is spent moving data from one address 
space to another In OS-9 Level Two. This 
involves several operations for each byte 
and slows I/O operations and other inter- 
task communications down quite a lot. The 
special hardware on this new CPU board can 
move blocks of data at 2 cycles per byte. 
At two megahertz that comes to one million 
bytes per second. I understand that, all 
things taken together, the new system runs 
OS-9 substantially faster than what I have 
now. I want to find out for myself. If you 
see an advertisement from me in the classi- 



A NULL DEVICE 

One of the nicest features of OS-9 
(both levels) is the relative ease with 
which it can be adapted to new hardware. 
For example, there is a module included 
with the operating system called ACIA which 
is responsible for interfacing the rest of 
the system with ACIAs (Asynchronous Commu- 
nications Interface Controllers, or serial 
ports). There is another module called PIA 
which does a similar job for parallel 
ports, and another module which deals with 
whatever type of disk controller you have - 
more modules if you have more than one type 
of disk controller. If you feel the need 
you can add more Device Drivers (the name 
of this type of module) any time you like. 
If you want to write your own driver, it Is 
good to have an example to work from. The 
source for ACIA and PIA (available from 
Microware) are both good starting places 
though I found ACIA more useful . 

There is a rather odd sort of device 
which is available with most operating sys- 
tems, but not OS-9. I have seen it called 
DUMMY and NULL. This device makes anything 
written to it disappear, and returns an 
endfile if it is read from. It is surpris- 
ing how often it is nice to have any easy 
way to throw data away. 

The Null Device Driver that I am going 
to present here is a SCF (Sequential Char- 
acter File) type device. The requirements 
for this kind of driver are given in the 
OS-9 System Programmer's Manual, but in 
general there are six entry points: Ini- 
tialize device, read, write, get device 
status, set device status, and terminate 
the device. This driver is so simple that 
of those six, five just clear the carry bit 
and return. Read Is the only operation 
requ 1 r 1 ng more than two 1 1 nes of code . Read 
Is supposed to return with the character 
read in accumulator A. If an error takes 
place, the carry bit should be turned on, 
and the error code placed in accumulator B. 
We want to return end-of-file. which is an 
error, and I have found that is a good idea 
to return null (Chr(O)) as the character 
read even lf it is end-of-file. I return 
the end-of-file from the driver though it 
is usually generated by the SCF file manag- 
er. If you want to modify the program such 
that the file manager is the module that 
generates the end-of-file. load accumulator 
A with the end-file character which can be 
found in the path descriptor (pointed to by 
Y) and return with carry clear. 

A Device Driver may be used for several 
devices provided that they use the same 
hardware. Each individual device is 
described by a "Device Descriptor" which 
includes everything unique to a particular 
device such as the address of the device. 
The NL device descriptor is at the bottom 
of the program. It will be loaded into mem- 
ory at the same time as the Driver although 
it will show up as a separate module In the 
module directory. 
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DOCUMENTATION FOR NULL DEVICE 
DESCRIPTOR 

If the file Null is loaded and the module 
NL is linked a new device called /NL will 
become available for Input and output. 

0S9 Load Null 
0S9 Link NL 

The device NL will accept input in any 
quantity and simply make it disappear. If a 
read is directed at it, it will reply <end 
of fne>. Other than eating data without a 
sign It acts like a perfectly normal SCF 



type device, 
one I 



a very fast and efficient 



Example: 

0S9: asm MyProg o #48k >/nl & 

Would assemble MyProg in background and 
make all its (non-error path) output disap- 
pear. 

Note: Be careful when using /NL for 
Input. Some programs (such as debug) don't 
respond to <End of File> - these programs 
will act very oddly if /NL Is used as the 
input device for them. 



NULL PROGRAM 

Microware OS-9 Assembler 2.1 08/05/84 22:40:30 
Dummy l/O driver - Definitions 



Page 001 



00001 

00002 

00003 

00004 

00005 

00006 

00007 

00008 

00009 

00010 

00012 

00013 

00014 

00015 

00016 

00017 

00018 

00019 

00020 

00021 

00022 

00023 

00024 

00025 

00026 

00027 

00028 

00029 
00030 
00031 
00032 
00033 
00034 
00035 

00036 
00037 
00038 
00039 
00040 
00041 
00042 
00043 
00044 
00045 
00046 
00047 
00048 
00049 
00050 
00051 
00052 
00053 
00054 
00055 
00056 



* 

* 
* 
* 



NAM Dummy I/O driver 
TTL Definitions 



Dummy 

return end of file to 
Put any output down th 
No error returns 
Public Domain software 



OOEl 
0082 
0000 
D OOID 
D OOID 
OOOD 

OOOE 
0011 
0012 
W 0012 
W 0015 
W 0018 
V OOIB 
W OOIE 
W 0021 



87CD002E 



07 

446DF9 
01 

16000F 
16000E 
160009 
160006 
160003 
160000 



Type 
Revs 



Hemsize 



DumNam 
Entry 



IFPl 

ENDC 

set 

set 

MOD 

ORG 

equ 

fcb 

TTL 

fcs 

fcb 

Ibra 
Ibra 
Ibra 
Ibra 
Ibra 
Ibra 



lJuly82 Peter Dibble * 

any. read * 

e bit bucket. * 

* 

as of 19Feb83. * 

use /DO/DEFS/Defslist 

DRIVR+OBJCT 

REENT+2 

Dummy 1 , DumNam , Type , Revs , Ent ry , Mems ize 

V.SCr leave space for SCFman overhea 



READ.+WRITE,+EXEC 
Dummy I/O Driver 
/Dmy/ 
1 

Init 

Read 

Write 

GetStat 

PutStat 

Term 



driver mode 

Edition number 



0024 
0024 
0024 
0024 
0024 

0024 5F 

0025 39 



0026 
0026 
0027 
0028 
002A 
002B 
002E 



OOFl 
0000 
OOOD 
OOOE 
0011 
0013 
0015 
0018 
OOIB 
OOIE 



4F 

53 

C6D3 

39 

848D35 



Init 

Write 

GetStat 

PutStat 

Term 



Read 



Dummy 1 



clrb 
rts 



clra 

comb 

Idb 

rtfi 

emod 

equ 

TTL 



#E$EOF 



zero return code 
Do nothing 



set carry flag 
return end of file 
return 



Device Descriptor 



NL device descriptor 






87CD001E 

07 

FFOOOO 

0100 

4ECC 

5343C6 

446DF9 

BD5979 



Type 



DDNam 
FMNam 
DRVNam 

DDend 



set 

mod 

fcb 

fcb 

fcb 

fcs 

fcs 

fcs 

emod 

equ 



DEVIC+OB JCT 

DDend , DDNam , Type , Re vs , FMNam , DRVNam 

READ.+WRITE.+EXEC. modes 



$FF,0,0 

1,DT.SCF 

/NL/^ 

/SCF/ 

/Dmy/ 



PORT ADDRESS OF 

Options 

device name 

File Manager Name 
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COLUMN TWO 



OS-9 LEVEL TWO VERSION 1.1 

I just installed OS-9 Level Two Version 
1.1. Finally It's not "preliminary" any 
more. Since DS-9 never was very unreliable 
1t 1s hard to tell whether it is more reli- 
able, but it is very easy to appreciate the 
new utilities. 1 spent months writing a PWD 
program. It prints the name of the current 
data or execution directory. I hoped some- 
day maybe I could sell that program. Well, 
Microware beat me to It. The new versions 
of OS-9 include PWD and PXD, Print Working 
Directory and Print execution Directory. 
They also added a DELDIR command which 
deletes a directory with all the files in 
1t, a command called IDENT which displays 
information about modules 1n files, a file 
comparison utility called CMP. and two com- 
mands called B2NEX and EXBIN which convert 
a file to and from Motorola standard 
S-Record format. DCHECK, the program which 
checks disk structure, now seems to work 
correctly, and DSAVE, the command which 
constructs a procedure file to copy groups 
of files, has been substantially enhanced, 
but Level Two users will have to continue 
to live with numeric error messages. A com- 
mand called PRINTERR, which is supposed to 
instruct the operating system to use text 
error messages, wasn't on my distribution 
disk. 

An important new feature in OS-9 is 
support for XON/XOFF . The ASCII character 
set includes 32 Special codes such as back- 
space ($08) and escape ($1B) which don't 
generally represent printable characters, 
but still have defined meanings, XON and 
XOFF are among the more useful of these 
special codes. If, for instance, you have a 
terminal which usually runs at 19.2KB, but 
can only accept input at about 200 charac- 
ters per second when it is In insert mode. 
it would be nice to be able to constantly 
adjust the speed at which the computer is 
transmitting to match the speed at which 
the terminal can receive. In general you 
can't do that, but often it is sufficient 
to be able to tell the computer to "hold 
it." and "go ahead." If the computer can 
deal with XOn/XOff protocol, it will "hold 
it" whenever it receives an XDff, and "go 
ahead" whenever it receives an XOn. There 
are quite a few terminals and printers 
around which run much better when they are 
attached to a computer which supports XOn/ 
XOff. It is Interesting to note that XOff 
(often called DC3) is entered as <CTRL>S, 
and XOn (DCI) is <CTRL>0. In order to use 
this protocol you've got to find some char- 
acter other than <CTRL>0 to use as the 
"quit" character. I wonder whether Frank 
Hogg is going to be able to adjust DynaStar 
so it can live without <CTRL>Q and <CTRL>S. 



bootstrap just on the principle of the 
thing. The modules; in the bootstrap are 
automatically loaded when the system is 
booted, packed efficiently into memory, and 
made permanent. It sounds as though, if you 
have enough memory, it would be a good idea 
to include in the bootstrap file all the 
modules you would like permanently In memo- 
ry. Don't do it! Modules in the boot file 
are not only permanently In storage, they 
are also permanently attached to the other 
programs in the boot. Say you put a P-Code 
interpreter in the bootstrap - when you 
link to that module in order to use It, you 
drag everything else in the bootstrap along 
with It. If you have a 48K bootstrap you 
would only be able to run programs which 
use up to about 12K total. Modules you 
expect to link to should not be Included in 
the bootstrap. If you include a utility 
command such as COPY, you may find that you 
can only use a relatively small amount of 
memory with COPY. The best way to handle 
commonly used commands is to merge just 
less than some small multiple of 4K of them 
into a utilities file and load it using a 
LOAD command in the startup file. Since my 
system allocates memory in blocks of 4K, 
small programs like COPY and PWD only waste 
memory if they are loaded by themselves. By 
collecting groups of programs together you 
use memory more efficiently, essentially 
keeping two or more programs in the space 
normally allocated to one. If your version 
of OS-9 allocates memory in different sized 
hunks, the size of the group of programs 
should be changed to reflect the new con- 
straints. Users of Level One systems don't 
have to worry about any of this stuff. 

The first time I generated a new boot- 
strap was a little bit intimidating. It Is 
Important to realize that, provided you are 
marginally careful (don't epill chocolate 
milk on an important disk, etc.). the worst 
you can do Is waste your time. If you don't 
have a lot of memory the chance to remove 
unused device descriptors from the boot- 
strap may be worth the trouble involved In 
running 0S9GEN. If you want to change any 
modules which are in the bootstrap 
(addresses In Device Descriptors for 
Instance), the cleanest way to do it is to 
modify them them with DEBUG, save the modi- 
fied modules, fix their CRC with VERIFY, 
and build a new bootstrap with the modified 
modules. A module must be saved on disk In 
order to be included in the bootstrap. You 
should use the SAVE command to create files 
containing each module you might want In 
the new bootstrap. Build a file with the 
names of those files you want to combine 
Into the new bootstrap, and use that list 
Of files as input to 0S9(iEN. Finally use 
DCOPY to copy all the other files on your 
system disk over to the new one. 



BUILDING A NEW S7STEM DISK 



GENERATING A NEW BOOTSTRAP 

One of the first thi ngt I do with a new 
version of DS-9 is put together a new boot- 
strap. There is nothing really wrong with 
the bootstrap that comes with the system, 
but I have my own Device Descriptors and 
Drivers, and even if I didn't need to, I 
probably would want to re-generate the 



I have many files on my system disk that 
are not part of the OS-9 operating system. 
An important part of Installing a new ver- 
sion of OS-9 which Is not mentioned in the 
manuals is copying all the non-OS-9 files 
you need onto your new system disk. I have 
discovered an easy way to do this. I Imag- 
ine most of you 0S~9 users already know 
this trick, but I wish someone had told me 
about it a year ago. By running DSAVE on 
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your old system disk you can create a file 
containing a copy command for each of the 
files on your old system disk. If you add a 
"-X" as one of the first few lines in that 
file Tt won't quit if one of the commands 
fails. The copy commands for files that are 
already on the new disk will fail, but the 
procedure will precede to the next command 
instead of quitting. The result is a disk 
with all the files you want on it. 



use multiple processes to get at lots of 
storage wnen you can spin off a task that 
can run in isolation. Communicating between 
processes is a harder problem than running 
them in isolation. Several method for com- 
munication will be developed in later col- 
umns . 



USING MULTIPLE PROCESSES 



Most of the programming I do is on machines 
with far more than 64K available to each 
program. It is easy to get used to having 
effectively unlimited memory. The 6809 can 
only use 64K, but with the help of OS-9 
Level Two (not Level One) it is possible to 
use more memory than most people can 
afford. Over the next few months I expect 
to spend some time discussing various ways 
of doi ng this . - 

One of the basic facilities in OS-9 
(and most other sophisticated operating 
systems) is called FORK. The effect of f:ORK 
is to set a program up and start it running 
without interfering with the program which 
FDRKed It. Each FORKed program is called a 
Process or a Task. A process can run for 
all practical purposes at the same time as 
the program that FORKed it. Part of setting 
a process up is finding enough memory for 
it to run. In OS-9 Level Two each process 
runs in its own "address space"... that is. 
no user process shares any memory with any 
other process except by special arrange- 
ment. If you have enough memory, each pro- 
cess can occupy all of its 64K address 
space except a shred reserved for OS-9. 

I have been spending a lot of time 
writing a program which I call a "smart 
terminal" program. It started out as a pro- 
gram to allow me to communicate with a 
variety of computers without having to 
unhook my terminal from my computer, and 
fuss with half/full duplex. It just keeps 
growing. One thing I decided to do was 
include a way of printing a screen full of 
data. You can't just stop everything and 
print the screen; it would take so long to 
print that the input buffer from the modem 
would overflow, and at best data would be 
lost. A solution is to use a FORKed process 
to print the screen. Once I realized that I 
could start a process to print the screen, 
I carried it a step farther and fixed 
things so I can ask to have lots of screens 
printed, start a process for each screen, 
and let them queue up for s chance at the 
printer while the process doing the smart 
terminal bit runs jcheerfully along. At 
about 4K per process (the minimum alloca- 
tion on my Level Two system) I can queue up 
about 20 screens in the 200K I usually have 
available. Using the more efficient alloca- 
tion of storage available under Level One I 
could probably have queued up about 10 
screens in a 56K system. I admit this is a 
trivial example of the use of extended 
storage, but the point is that this is a 
simple example of the kind of thing you can 
do with extended storage. It is easiest to 
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The module is reentrant, so only the 
variable storage needs to be allocated 
for each process beyond the first. 
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THE FORK SUPERVISER SERVICE 
REQUEST 



by-value parameter — changes don't get 
back to the invoking process. Still, for 
many jobs, the one time, one way communica- 
tion afforded by the parameter area is suf- 
ficient . 



A large numoer of the exciting things that 
can be done with OS-9 involve processes. 
Every program running under OS-9 is a pro- 
cess. Each process runs as if it had the 
machine to itself (except for speed). When 
a new process is started, OS-9 loads the 
Program module for the process if it isn't 
already in core, creates a Process Descrip- 
tor for it, allocates the necessary amount 
of memory, gives it standard input and out- 
put files, and lets the new process go. 
One of the ongoing tasks of the operating 
system is to divide processor time between 
all processes so that the system's resourc- 
es are used as efficiently as possible, and 
all the processes run without too many 
noticeable jerks. You can tell OS-9 to 
favor a process by giving it a high priori- 
ty (with the SETPR command), or you can 
give a process a low priority If you don't 
much care how quickly it runs. 

A new process is created with the OS-9 
service request F$Fork. Before issuing 
this serv i ce request you must set up the 
registers as follows: 

X Address of the name of the 

module you want to FORK or the 
file that contains the module. 



Y 
U 



The size 
area. 



of the parameter 



The beginning address of the 
parameter area . 

The Language/Type code. That 
is, the type of module you 
want to fork. Baslc09 has to 
be treated differently from 
object code. 

The amount of optional storage 
to give the new process. 



COMMUNICATIONS VIA THE PARAMETER 
AREA 

When the FORK Service request is used to 
start a new process OS-9 is able to send a 
block of data to the new process using the 
parameter area. The new process will be 
started with X pointing to the start of a 
copy of the parameter area and D containing 
the length of the parameter area. In lan- 
guages other than assembler, the parameter 
area can be found by noting that the param- 
eter area is the place where the shell 
places the command line parameters for a 
program. The shell usually starts programs 
by FORKing them, so in any language, if you 
can get to the command line parameters, you 
can get at parameters passed through Fork 
in the same way. 

By using the parameter area you can 
pass a lot of information to a new process, 
but you can't get anything back through the 
parameter area. Remember that the parame- 
ter area gets copied into the new process's 
address space. It is like a Pascal pass- 



ASSEMBL7 LANGUAGE PROCEDURES FOR 
FORKING PROCESSES 

Neither Baslc09 nor Pascal has all the nec- 
essary functions for dealing with forked 
processes, but they can be reached through 
assembly language subroutines. I have 
Included two short assembly language sub- 
routines which should help. StrtTask, and 
WaitTask are meant to be called from 
Basic09, though modified versions could be 
called from Pascal or any other normal lan- 
guage, StrtTask starts execution of a pro- 
cess, and WaitTask waits until a child of 
the celling process completes before 
returning to the caller. These aren't 
examples of elegant coding, but they are 
good enough to play around with from 
Basic09. The 6aslc09 programs Driver, and 
BTest are respectively a driver for the 
assembly language modules and a stub for 
testing them. 

StrtTask is an Interface between a 
BasicOB program and the OS-9 Fork service 
request. Normally, a fork is done with the 
SHELL statement in Ba8lc09. By using 
StrtTask Instead of SHELL to start "child" 
processes, a program can gain better con- 
trol of the parameters. StrtTask allows 
full control of the F$fork system service 
request . 

The first parameter which StrtTask 
expects Is the name of the module to be 
started. It should be passed as a charac- 
ter string with a terminator, such as a 
space or carr 1 age return . af ter the 1 as t 
character of the module name. If the mod- 
ule might not be In memory, the name of the 
file which should be loaded to get the mod- 
ule should be the first parameter Instead 
of just the module's name. The F$Fork sys- 
tem service request description In the OS-9 
System Programmer's Manual has more details 
about this, and all the other parameters 
for StrtTask, 

The second parameter is the process 
number of the new task. It is a byte field 
which need not be initialized. StrtTask 
will place the process number of the newly 
started process in this byte. This is the 
only parameter which Is returned from 
StrtTask, The process number is useful If 
you want to communicate with the new pro- 
cess, or to wait for a particular process 
to complete. 

The third parameter is the language/ 
type byte which describes the module you 
want to run as a child process. The easi- 
est way to discover the proper value for 
this byte is by checking the module you 
want to fork. You can see the language/ 
type byte for a module by loading it and 
doing a MDIR E command, or by doing a IDENT 
command on the file the module is In. 
Remember that this byte Is displayed In 
hex. Object code programs (generated from 
assembly language) generally have a 
language/type byte of $11, or decimal 17. 
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The fourth and fifth parameters are the 
■ength of the parameter area to be passed 
-o the forked process, and the parameter 
irea itself. The parameter area can be any 
;ype of data you want to pass to the new 
process. The length of the parameter area 
is passed as an integer. If you Invoke a 
module which is usually started from the 
shell, the parameters should be a character 
string terminated with a carriage return. 
If you want to invoke a module which runs 
under Basic09, it is particularly important 
to include the carriage return at the end 
of the parameter area (which contains the 
name of the BasicOS I -code module to run 
and any parameters for it). Strange things 
happen if you don't. 

The last parameter is the amount of 
optional storage space you want to give the 
new process. This is the number usually 
placed after the "#" on a shell command 
line. The number can range from zero to 
255 (it is a byte field), and may only be 
in units of pages, not Kbytes. 

If the fork service request Itself gets 
a bad return code. It will be returned to 
the calling program as an error. In gener- 
al the new process will still be running 
when StrtTask returns to the calling pro- 
gram, so there is no way to know what the 
completion code of the new process is 
(going to be) , 

Sometimes you may want to start a pro- 
cess going and continue without waiting for 
the new process to complete, but you may 
need to wait for it to complete at some 
point. This is where WaitTask comes in. 
WaitTask will wait (just sit there) until 
one of its children (a child of the program 
that called WaitTask) completes. If there 
are several children, the first one to com- 
plete will let WaitTask return to its call- 
er. If there are no children, WaitTask 
will return with an error. If a child pro- 
cess terminates before It Is waited for. 
its process descriptor will linger around 
in memory until a wait Is done by the 
parent process . 

WaitTask has two parameters, both of 
which are set by WaitTask. The first 
parameter Is a byte containing the process 
number of the process whose completion let 
WaitTask return. The second parameter is 
the completion code of that process. If 
there are several children that might ter- 
minate, the process number parameter can be 
used to cause the calling program to keep 
calling WaitTask until the necessary pro- 
cess completes. 

To use this package of modules 
(StrtTask. WaitTask. Driver, and BTest): 

Assemble a file containing StrtTask 
and WaitTask 

asm StrtTask o #24k 

Save the packed form of BTest 

BASIC09 

in BTest 



load StrtTask and WaitTask 

load StrtTask 
or if you are still In BasicOS 

$load StrtTask 



Type in Driver 
program} 

run Driver 



{the basic driver 



There are a lot of interesting things 
that can be done with these modules. You 
can fork any program you want, not just 
packed BasicOS modules, but the special 
features of the shell, such as I/O r^irec- 
tion, aren't provided by StrtTask. You 
don't need to wait for the new process to 
complete, but if the new process does I/O 
to standard paths, it can be very hard to 
tell what is going on on the screen. If 
you haven't made a mistake that causes sev- 
eral processes to use the terminal for I/O 
at the same time yet, you should. It is 
educational . 

The thing about new processes that par- 
ticularly excites me is that under Level 
Two each new process gets a new address 
space with up to 64K . The main problem 
with the modules included with this column 
1s that there is only one-way communication 
with forked processes. The parameter area 
goes from the parent to the child, but the 
child only sends a completion code back to 
the parent. There are easier ways to com- 
municate. We'll get to them later. 



save 
pack 
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A version of StrtTask with support for 
pipes appears in Column Ten. 



* 



STRTTASK-ONE 

ttl Start a subtask (called from Basic09) 

nam StrtTask 

* * 

* StrtTask is a subroutine for Basic09. * 

* Start a named module as a subtask. * 
"^ Let the new task run asynchronously. * 

* return the new tasks process number, and the * 

* condition code from the Fork. * 

* Calling sequence: * 

* run StrtTask (Name, Process_Num, Lang^Tjrpe, 

* Param_L, Param, Opt si2e) * 

* Name is any length, but has a valTd terminator * 

* (high bit set on last byte, or delimiter after it)''*' 

* Process_Num byte field, process number of new task-* 

* Lang Type byte field, language/type byte for * 

* forlted module. ^ * 

* Param_L^ integer field, length of parameter area. * 

* Param field or any type, parameter area to be * 

* passed to forked process. * 

* Opt^Size byte field, optional data area size in * 

* pages. * 

* Process_Num, and Return_Code are altered by * 

* StrtTask, no other parameters are. * 

IFPl 

use /HO/DEFS/defslist 

ENDC 
Type set SBRTN+OBJCT 
Revs set REENT+1 

rood TLen , StrtTask , Type , Revs , SEntry , 
StrtTask fcs /StrtTask/ 

fcb 1 version 
SEntry 

Idd 2,S get param count 

cmpd #6 are there 6 params? 

bne BadExit no; leave now. 

Idx 4.S address of module name 

Idy [16, Sl length of parameters 

Ida [12, sl type of module to invoke 

Idb [2A,Sj optional data area size 

Idu 20, S pointer to parameters 

0S9 F$Fork start the new process 

bcs BadExit2 

sta [8,S] save new process number 

clrb clear carry 

rts return 
BadExit 

coma set carry 
BadExit2 

rts return 

EMOD 
TLen equ * 

ttl Wait for a (child) process to complete 

nam Wait Task 
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Tfe -i- 

^^ WaitTask is a subroutine for Basic09 * 

^ Wait for the a child process to complete. * 

^'^ Return the process ID of the process that completed^' 

'^ in parameter one. * 

'^ Return the competion code of the process * 

''^ in parameter two. * 

-' This subroutine will wait using no CPU time until * 

* a child process completes. * 
^ If a child completed just before WaitTask was * 

* called, it will return almost immediatly. ^ 
^^ If there are no children, an error will be returned^ 

* with a process number of 0. * 

* Calling sequence: * 
"^ RUN WaitTask (Process^No, Comp_Code) * 

* both process no and Comp_Code are BYTE variables, * 

Type set SBRTN+OBJCT 
Revs set REENT+1 

mod WLen , Wai t Task , Type , Revs , WEnt ry , 
WaitTask fcs /WaitTask/ 

fcb 1 edition 
WEntry ^ 

clr IA,SJ zero the process ID 

Idd 2.5 param count 

cmpd #2 if not exactly 2 params then 

bne WBExit2 the caller is making a bad mistake 

0S9 F$Wait wait for a child 



bcs WBExit 
sta [A,S] reti 
stb [8,S] reti 



:urn the process ID 
:urn the completion code 

rts return 
WBExit2 

coma set carry 
WBExit 

rts return 

EMOD 
WLen equ * 

end 



DRIVER ONE 

PROCEDURE Driver 

DIM process No,Comp Code, Opt Size, Lang Type:BYTE 

DIM Farm L:TNTEGER - - - 

DIM nameTSTRING 

DIM Farms: STRING [20] 

(* Set up to call StrtTask which will fork the named 
(* module, passing it the parameter string in Farms. 



Opt_Size«U 

Lang Type*$ll \(* attributes of forked module (c 
Parms«^'§Test**+CHR$(13) \(* The parms must end wi 
Farm L-LEN (Farms) \(* The length of the paramett 



name*"Basic09 

grocess_No=0 
pt_Size«0 

^ -Nil \ /4. 1.^ .,_ ^ _ .- *» . J, , ^ (object code, program) 

with <CR> for Basic09 
__ ,_ length of the parameters must be correct 

(* Call assembler subroutines to Fork and wait for the started 
\* process 

tUN StrtTask (name, process No, Lang Type, Farm L, Farms, Opt Size) 
fUN WaitTask (process_No,Comp_CodeT 

^,;* Acknowledge that everything is done 

PRINT "Forked task complete" 

PRINT "Completion code for process "; process_No; " was "; Comp_Code 
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BASIC/BASIC09 

A month ago I Installed BaslcOS on my 
machine. I have been proud of not having a 
Basic on my computer, but OF (An OS-9/Flex 
copy program) requires BasicOS, so I swal- 
lowed my pride and installed Basic. I have 
spent too many hours breaking students of 
the bad habits they learned in elementary 
computing courses taught using Basic to 
have any affection at all for that lan- 
guage, but I think I could learn to love 
BaslcOS. It IS able to masquerade as 
Basic, but It feels just like a modern 
structured programming language to me. I 
am sure that there were valid marketing 
reasons for including "basic" in the name 
of BasicOS. but I wish they had named it 
Advanced Programming Language or something; 
I would feel much more comfortable learning 
to love the language if it had a different 
name . 



systems call the operation 
which spawns a new process 
FORK. 

Parent/Child The process that spawns a new 
process ls called the Parent 
(used to be father) of the new 
process. The new process is 
said to be the child (used to 
be son) of the process which 
spawned 1t. The family tree 
analogy can be taken as far as 
you like; processes can have 
siblings, ancestors, descen- 
dants. . . 



Asynchronous No t depend 1 ng 

clock. 



on 



the same 



Don't take these definitions as gospel. 
They are superficial -- barely enough to be 
useful in the context of this column. 



COMMUNICATION VIA THE PARAMETER 
AREA 



INTERPROCESS COMMUNICATION 

Last Column I promised to continue 
wrestling with the problem of communication 
between processes ... Writing about pro^ 
cesses without using technical terms is 
getting to be too much for me. I am going 
to give loose definitions of some of the 
Important terms here. 

Procsss or Task 

A module (Program, subroutine, 
or whatever) which the oper- 
ating system views as an 
Independent piece of work. A 
program Is usually a process 
though sometimes a program is 
divided into several process- 
es. 

Coneurrvnt processes 

Strictly speaking concurrent 
processes must actually run at 
the same time. This requires 
a separate processor for each 
process. The term Is some- 
times loosely applied to pro- 
cesses (like OS-9's) that are 
actually using one processor 
in turns, but seem to be run- 
ning at the same time. 



Dispatch 



Schedule 



Spawn 



Give a process access to the 
processor. The operating 
system will dispatch each 
active process in turn. Only 
one process can be running at 
any time, so the operating 
system must have a way of 
Interrupting a process as well 
as dispatching it. 

Closely related to dispatch. 
If the operating system shows 
any intelligence at all about 
which process to dispatch 
next, it can be said to 
schedule them. 

Create a new process. This is 
a more general term than FORK 
because not all operating 



Passing a parameter area to a FORKED 
process is simple, but of limited useful- 
ness. The limitations associated with com- 
munication with processes via the parameter 
area are that the communication is general- 
ly one way, and that, since a copy of the 
parameter area is made for the new process, 
large parameter areas will use a lot of 
memory, and increase the length of time the 
FORK operation takes. Under OS-9 Level 
One. all processes share one 64K address 
space along with all the assorted system 
overhead (OS-9 itself, memory mapped I/O, 
etc). Spawning a new process with a 20K 
parameter area will cost 40K just for the 
parameter area (20K for the original and 
20K for the new process's copy). That kind 
of thing can chew up a lot of memory in 
short order. With Level Two. the memory 
problem isn't so important, but, unless you 
have the Glmix III version of OS-9, it is 
time consuming to copy a large parameter 
area into a new address space. 

Some of the characteristics of the 
parameter area make it possible for new 
families of bugs to creep Into programs 
that use them for inter-process communica- 
tions. Under OS-9 Level Two. each new pro- 
cess gets its own address space. There is 
no sign of any other process in that 
address space except a copy of the parame- 
ter area passed from the parent process. 
If the parameter area Includes any address- 
es, they will be pointing to places that 
were significant In the parent's address 
space. In the new process's address space 
those addresses may be empty or contain 
something unexpected. The tricky thing 
about this is that. under Level One, 
addresses in the parameter area are mean- 
ingful. Since there is only one address 
space, the addresses just reach out Into 
the parent's memory and grab, or change, 
the data the parent pointed them at. Being 
able to read and change data in the parent 
process's memory is a mixed blessing. 

Let's say you want to print the con- 
tents of an array without stopping to wait 
for the printer, A very good way to do 
this is to spawn a task to do it. If you 
pass the array to the new task as a parame- 
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ter, everything will be fine except that, 
if the array is large, you may run out of 
memory. If you conserve memory by passing 
only the address of the array, everything 
will still be fine (under Level One) pro- 
vided that neither process changes the 
array while the child is running. If the 
child changes the array, it is very likely 
to be a surprise for the parent. If the 
parent changes the array (e.g., by starting 
to work on new data) the child will see the 
changes, and print an array that is part 
the old one and part the new one. 

It would not be too hard to track down 
the reason for that kind of garbled print- 
ing, but there is an especially virulent 
form of that bug which not only is hard to 
find once you set out to look for it, but 
also sometimes doesn't show up under most 
forms of testing and looks suspiciously 
like a hardware glitch. The operating sys- 
tem lets each process run for a fraction of 
a second, then interrupts it and dispatches 
another process. If you read some of 
another process's data, then change it and 
put it back (something like A = A + 1, 
which reads A, adds 1 to it, and stores the 
result in A), you can't be sure that the 
other process hasn't changed the data 
between the time you read it and the time 
you wrote it unless you have masked inter- 
rupts for the duration of the operation. If 
some process changed the value of A in the 
middle of the add. the new value of A will 
be wiped out when the result of the addi- 
tion is put into A. Every process looks 
entirely innocent when viewed alone, but, 
taken together, they are chaos. If you 
change a program with this kind of error, 
even to add diagnostics, the problem may 
seem to disappear. The timing has to be 
very precise for this kind of error to show 
up, and (Murphy's Law being what it Is) the 
timing Is never what you want It to be. 
Finding and fixing this kind of bug Is the 
kind of thing that makes a programmer want 
to join a commune and raise corn. 

OS-9 Level Two prevents this kind of 
trouble with the parameter area by making 
addresses in the parameter area unusable. 
Some programmers working in OS-9 Level One 
without a crystal ball to predict the 
nature of Level Two passed address to other 
processes. Their programs (I believe 
DYNASTAR/DYNAFORM la an example) have 
restrictions when they are used under OS-9 
Level Two because under Level Two those 
addresses are not meaningful. 

If addresses are included in the param- 
eter area, and you are using Level One, a 
process can send data to its parent by 
changing the parent's variables. If you 
prudently don't use that questionable 
trick, this type of communication is like 
heredity: strictly from parent to child. 



DATA MODULES 

The parameter area is certainly the 
simplest path for inter-process communica- 
tion, but there are are several other meth- 
ods. The most powerful tool for Inter- 
process communication Is the "data module." 
The data module is a rather mysterious mod- 
ule type Intended to be used to store col- 
lections of constant data. The usefulness 



of data modules stems from the way OS-9's 
LINK system service request works. 

The LINK request returns the address of 
the module you link to. Level One simply 
returns the address, but Level Two must put 
the module in question into the address 
space of the process that does the LINK in 
order to be able to provide a meaningful 
address. If the module is marked "reent- 
rant," the system memory map will be 
adjusted so the memory containing the mod- 
ule being linked to will appear in the 
address space of each process which Is 
LINKed to it. This is a way to make a 
block of memory accessible to several pro- 
cesses. By making a module reentrant you 
assure the operating system that several 
processes can use the module without inter- 
fering with one another. Usually that 
means nobody changes the module. In the 
case of a shared data module it is some- 
times a good Idea to lie to OS-9. If you 
let a single process change a reentrant 
data module while other processes only read 
what's there, there is not much chance of 
getting into trouble. Data modules can be 
written into by many processes, but this 
requires careful management. The problems 
which can plague Level One users playing 
with two way communications through the 
parameter area all apply to shared data 
modules which are written into by more than 
one process. 

A rather annoying problem with data 
modules ls that they must be loaded from 
disk like any other module. It Is possible 
to build a module in memory, but the system 
service request which forces OS-9 to 
include the module in Its directory of mod- 
ules in memory Is a supervisor state 
request. It is possible to circumvent that 
restriction, but the method Is too involved 
to tackle this month. 



LOCKING DATA MODULES 

It Is practical to have a data module 
with two or more "writers" because there 
are ways to "lock*- a data module. A lock 
is a system for checking that a resource is 
free. then, if it is free, marking it "in 
use." Every program that uses a shared 
resource must check and respect the lock in 
order for it to be effective, but there is 
no way to enforce the locking In such a way 
that no program can get at the shared mod- 
ule without going through the locking pro- 
tocol (GIMIX III might provide a way to do 
this). The easiest way to lock a module 
(or anything else) is to write a pair of 
operating system services to lock and 
unlock any specified resource. These ser- 
vices are usually called ENO/DEO after the 
sensible English words enqueue and dequeue, 
or P/V after two Dutch words. Dijkstra is 
responsible for the P/V terminology; IBM 
may have thought up ENO/DEO. Perhaps I'll 
write the OS-9 function handlers for P and 
V someday, but until those services are 
available, modules can be locked quite 
effectively in any assembly language pro- 
gram. 

There are several Instructions in the 
6809 Instruction set which can read and 
write memory all in one Instruction. 
Altering a byte by reading and writing it 
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In one instruction prevents any otner pro- 
cess from accessing the byte in the middle 
of the alteration. The machine instruc- 
tions that read and write in one instruc- 
tion are: shift instructions, rotate 
instructions, increment, decrement, comple- 
ment, and negate. The instructions which 
are usually used for "locking" a module are 
increment and decrement. The basic idea is 
that you set aside a locking byte in the 
data module with an initial value of -1. 
To lock the module, increment the byte, 
and, if increment returns with the zero 
flag set, continue; the module is locked. 
If the zero flag is not set some other pro- 
cess has the module locked, so decrement 
the locking byte, and sleep for a while... 
then try again. See the assembly language 
modules Lock, and UnLock, for examples of 
this procedure. 

The LINK service request Is only able 
to find modules that are already in memory. 
If the module is not ln memory it must be 
loaded from disk using the LOAD service 
request. This problem could be dealt with 
by writing two assembly language subrou- 
tines, one to do LINKs, the other to do 
LOADS. This Offers the most flexibility, 
but requires the calling program to know 
more about OS-9 than I like. The assembly 
language program that accompanies this col- 
umn attempts to load a module from the exe- 
cution directory if it can't be found in 
memory. The problem with this approach is 
that the file which contains the data mod- 
ule must have the same name as the module. 

Tne data module Itself is created by 
the assembler. The main difference between 
a data module and a program module is that 
a data module has no permanent storage size 
in the module header, and no execiStable 
code . I use the execution offset field in 
the module header to point to the beginning 
of the shareable data. By convention, I 
use the first byte In the shareable data as 
a locking byte. For OS-9 Level One users, 
it is good to keep the module to a multiple 
of 256 bytes. Under Level Two, a module 
loaded by itself will use a multiple of the 
page size (usually 4096 or 2048 bytes), but 
a module loaded from a file containing sev- 
eral modules will share a page with other 
modules from that file 1f it can. 

Together, the assembly language modules 
SLink, SUnlink. Lock, and Unlock, provide 
the tools necessary for a BasicOS program 
to use shareable data modules. Before a 
data module can be used. It must be linked 
to; SLink returns the address at which OS-9 
placed the data module. This address will 
be usable until the module is UnL inked. 
Before any data in the module is used or 
changed, the module should be locked by 
calling Lock. Lock will not return control 
to the calling program until it has control 
of the data module. It would be possible 
to rewrite lock so it would return with an 
error code if some other process had con- 
trol of the data module, allowing the call- 
ing program to choose to do something other 
than wait if the module is not available. 
As soon as possible after locking the data 
module, it should be unlocked to release 
other processes waiting for the data mod- 
ule. Before stopping, a program that links 
a module should unlink it. OS-9 maintains 
a counter of how many times a module has 
been linked to. and deletes the module from 
memory when its link count goes to zero. 



I have included two trivial BasicOS 
programs to demonstrate module locking. 
Calc only calculates the sum of the squares 
of a list of numbers, but it could be the 
mainstay of a mail system, a matrix manipu- 
lation routine, or a print spooler (to name 
a few possibilities), Driver2 is a program 
who's greatest virtue is that It calls 
Calc. There are two forms of locking going 
on in the Driver-DataMod-Calc system: the 
first byte of data in DataMod is used by 
Lock. The second byte of data ln DataMod 
is used for communication between Driver2 
and Calc. Each process waits for this byte 
to take on a value set by the other process 
before It accesses the rest of DataMod. 
This is a very simple protocol which can 
only be used in trivial cases such as sig- 
naling between two modules. In this case, 
the main lock is used to prevent several 
nodules from trying to change the communi- 
cations byte at the same time. Once a pro- 
cess gets the lock, no other process can 
get it until the process holding the lock 
releases it. The process which has the 
lock can use the communications byte, and 
the rest of the data module, to call for 
the services of Calc In an organized fash- 
ion, 

I use a module from last month's column 
called StrtTask in this set of programs. 
If you are especially interested in memory 
efficiency, merge the file containing the 
StrtTask module with the file containing 
this month's assembly language modules. 
Calc must be packed in order to work (at 
any rate, I can't puzzle out any reasonable 
way to use it in source form). To make the 
contraption go, load the file containing 
SLink. SUnLInk, Lock, and UnLock. If 
StrtTask is in a separate file you might 
want to load that too; then start up 
BasicOS and run Driver 2. Driver 2 will pause 
for a while, starting up Calc. then ask for 
a number five times. Give It small numbers 
— they have to fit into byte variables. 
When all five numbers are entered, Calc 
will calculate the sum of their squares 
which will be displayed by Dr1ver2. If you 
want to try It again, reply Y to the next 
prompt. The last thing Drlver2 will do 
before ending Is ask whether you want to 
shut down Calc. You do. In a system with 
several processes using Calc you would want 
to leave it running, but, with only one 
process using Calc. it will Just be a nui- 
sance if it is not cleaned up when its one 
user terminates. 
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LOCKER PROGRAM 

NAM SLink 

yc )St 

^' SLink * 

'*' Attempt to link to a module. * 

^i If it isn't found attempt to load it. ^ 

^'^ Return the address of the module header, and the * 

* entry address. * 
*' Errors: '^ 

* 1 Wrong number of arguments in parameter * 
'^ list. ^ 

* other Return code from F$Link, or F$Load. * 

* * 

"^ Calling sequence (from Basic09) is: * 

* RUN Link (Module Name, Module Type, * 

* Header^Addr, Entry Addr) * 

* Module_Name is a cKaracter string containing the * 

* name of the module which should be linked * 

* to. It should be terminated with a <CR>. * 

* Module_Type is a byte containing the language/ * 

* type of the module. A data module would be * 

* $iD. . * 

* Header_Addr is the address of the module header of* 

* the linked module. It is returned from * 

* Link. Integer field. * 

* Entry_Addr is an integer field which is used to * 
^ return the address of the entry point of * 

* linked module. * 

•k it 

use /hO/defs/defslist 

endc 

TTL Subroutine callable from Basic09 to do Link SSR 

MOD LinkEnd, LinkNam, SBRTN+OB JCT,REENT+1 , LinkEnt , LnkMemS 
LinkNam fcs /SLink/ 

fcb 1 version 
LnkMemS equ • 
LinkEnt 

Idd 2,S get parameter count 

cmpd //A must be four 

bne LinkErrl 

Idd 14, S get length of entry address field 

cmpd //2 

bne LinkErr2 

Idd 18. S get length of header address field 

cmpd //2 

bne LinkErr2 

Idx AjiS Module name*s address 

Ida [d,Sj Type/Language 

8shs U 
S9 F$Link 

bcc LinkRtn Carry clear; clean return 

puis U 

cmpb //E$NEMod Non-existent module? 

bra LinkErr2 no; bad error was bne 

Idx A.S Module name's address 

Ida [8,Sj Type/Language 

pshs U 

0S9 F$Load 

bcc LinkRtn 

puis U 
LinkErr2 

coma 

rts return with error code in B and carry set 
LinkErrl 

Idb #$FE error code of 1 

comb set carry 

rts 
LinkRtn 

stu L1A,S] Header address 

sty [18, S] data address 

puis U 

clrb clear carry 

rts return 

EMOD 
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LinkEnd ecu * 

NAM SUnLink 

* -k 

* SUnlink Unlink a Linked Module. * 

* Calling sequence (from Basic09) . * 

* RUN Unlink (Header Addr) * 

* Errors: " * 

* 1 Wrong number of arguments in parameter * 

* list. ^^ 

* other Error code from F$Unlink. * 

* * 

* Header_Addr is the integer address of the header * 

* returned from the link request for the * 

* module you want to unlink. * 

TTL Subroutine callable from Basic09 to do Unlink SSR 

MOD UnlkEnd,UnlkNam,SBRTN+OBJCT,REENT+l,UnlkEnt,ULkMemS 
UnlkNam fcs /SUnLink/ 

fcb 1 version 
ULkMemS equ • 
UnlkEnt 

Idd 2.S get parameter count 

cmpd #1 must be one 

bne ULnkErrl not one; error 

pshs U 

Idu [6,SJ get module header's address 

0S9 F$Unlink unlink the module 

puis U recover U 

* return code and carry set by F$Unlink 
rts return 

ULnkErrl 

Idb #$FE 

comb 

rts 

EMOD 
UnlkEnd equ * 

NAM Lock 

* * 

* lock Lock protocol * 

* Wait for a "lock*' byte to indicate unlocked, then * 

* lock the byte. * 

* Calling sequence: * 

* RUN Unlock (Lock^Addr) * 

* Errors: * 

* 1 Wrong number of arguments in parameter list. * 

* Lock Addr is the integer address of the byte used * 

* for the locking protocol. * 

TTL Subroutine callable from Basic09 to perform "lock" protocol 

MOD LockEnd, LockNam, SBRTN+0BJCT,REENT+1 , LockEnt , LokMemS 
LockNam fcs /Lock/ 

fcb 1 version 
LokMemS equ . 
LockEnt 

Idd 2.S get parameter count 

cmpd f/1 must be one 

bne LockErrl not one; error exit 
LockLoop 

Idx l^fS] Eet address of lock byte 

inc ,X test and set it 

beq Locked 

dec .X can't get it 

Idx f/2 interval for brief sleep (tunable) 

0S9 F$Sleep 

bra LockLoop 
Locked 

clrb turn off carry 

rts return 
LockErrl 

Idb #$FE 

comb 

rts return 

EMOD 
LockEnd equ * 

NAM UnLock 

* * 

* UnLock Perform the Unlock protocol * 

* Restore the "lock" byte to the unlocked * 

* state. * 
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RUN OnLock' aock^Addr) ^^ 

* Lock_Addr is the integer address of the byte ^ 

* used for the locking protocol. ^ 

TTL Subroutine callable from BasicOP to perforin UnLock 

MOD ULokEnd , ULokNaro , SBRTN+OB JCT , REENT+ 1 , ULokEnt , ULokMemS 
ULokNam fcs /Unlock/ 

fcb 1 version 
ULokMemS equ . 
ULokEnt 

Idd 2«S get parameter count 

cmpd //I must be one 

bne ULokErrl not one; error exit 

Idx [4,SJ get address of lock byte 

dec ,X release the lock 

clrb set carry bit off 

rts return 
ULokErrl 

Idb #$FE error code of 1 

comb set carry 

rts 

EMOD 
ULokEnd equ '^ 



NAM DataMod 

TTL A Lockable data module 

* This a generic data module. * 

^ It contains a locking byte and up to 232 * 

^ bytes of unspecified data. * 

MOD ModEnd,ModNam,DATA,REENT+l,LockByte,0 

ModNam fcs /DataMod/ 
fcb 1 edition 

LockByte fcb -1 

UnSpec fee /1234567890123A5678901234567890123A567890/ 40 
fee / 1234567890123456789012345678901234567890/ 80 
fee /1234567890123456789012345678901234567890/ 120 
fee /1234567890123456789012345678901234567890/ 160 
fee / 1234567890123456789012345678901234567890/ 200 
fee /12345678901234567890123456789012/ 232 
EMOD 

ModEnd equ * 
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CALC PROGRAM 

PROCEDURE Calc 

fit 

^ Calculate the sum of the squares of the numbers 

* stored in DataMod. 

A process signals that it wants service by storing a 
hex 01 in the byte one off the start of data in DataMod. 
When Calc sees a 1 in that byte, it calculates the suzn of 

^ the squares and puts it at 7 and 8 off the start of data in 

'^l DataMod, then sets the status byte (1 off the start) to hex 00 

''^ indicating that calculation is done. 

it 

DIM Module Name: STRING 

DIM Module~Type:BYTE 

DIM Header~Addr,Data Addr: INTEGER 

DIM Status"Addr, Array Addr, Return AddrrlNTEGER 

DIM sum, i: INTEGER 
rit ' 

(* Setup 

Module Type-$AO 

Module~Name-="DataMod"+CHR$ (13) 

RUN SLInk (Module Name, Module Type, Header Addr, Data Addr) 

Status Addr-=Data~Addr+l ~ - - 

Array_Sddr-Data Sddr+2 

Return Addr«=Data Addr+7 

POKE STatus AddrTO \(* set idle (ready for work) 

(it — 

(* Wait for the status byte in DataMod to 

(* indicate that an operation is waiting to be done. 

( 

WHILE PEEK(Status Addr)<>l DO 

SHELL "SLEEP 2*' ~ 

ENDWHILE 

WHILE PEEK(Status_Addr)-l DO 

sum»0 

FOR i-0 TO A 

sum*sum+PEEK (Array Addr+i) *PEEK (Array Addr+i) 

NEXT i ~ 

(* The calculation is done. Save the result 

POKE Return Addr, sum/256 

POKE Return;^Addr+l,M0D(sum,256) 

(* and indicate that the results are ready 

POKE Status Addr,0 

WHILE PEEK (Status Addr)-0 DO 

SHELL "SLEEP 2" " 

ENDWHILE 

ENDWHILE 

POKE Status Addr,0 \(* we're dead 

RUN SUnLinktHeader Addr) 

BYE 
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DRIVER PROGRAM 

PROCEDURE Driver2 

'': Driver for "Locker" 

^l Demonstates simple Module lock/unlock 



r* 



'^^ Operation: 

^' Link to DataMod 

* Fork Calc (a simple process for demonstration purposes) 
2 Wait for the second Data byte in datamod to become $00 
2 indicating that Calc is running, 

* Start of Loop 

* Lock DataMod 

* Store data into bytes 2, 3, 4, 5, and 6 off the start of 

* data m DataMod 

^Change the bvte at 1 off the start of data in DataMod to $01 
2 indicating that there is data in the module to be operated on 

* Wait for the second data byte to change $00 

* Get the result of the calulation (an integer) at 7 and 8 
'^ off the start of data in DataMod. 

* UnLock DataMod 

(* Loop until end is called for 

C* Lock DataMod 

t 9M^^f the the first data byte to $02 (which tells calc to stop) 
2 Wait for the first data byte in DataMod to change to a $00 

* UnLock DataMod 

* UnLink DataMod 

* All done 

DIM Header^Addr , i : INTEGER 

DIM Process Num, Module Type:BYTE 

DIM Param Len,Data Addr: INTEGER 

DIM Opt Size, op: BYTE 

DIM NumTINTEGER 

DIM Params: STRING 

DIM Module Name: STRING 

DIM NY:STRTNG 

Module Type=$40 
Header~Addr-0 
Data A3dr«0 

ModuTe Name«"DataMo"+CHR$($80+ASCC'd")) 

RUN SLTnk (Module Name, Module Type, Header Addr, Data Addr) 
(* Set up for FORK operation- 
Module Type-$21 \(* Subroutine/Object code 
Params«"Calc"+CHR$ (13) 
Param Len*LEN (Params) 
Opt ST2e«=10 

Module_Name«"Basic09"+CHR$(13) 

?+^^^?^^T*sk(Module_Name, Process Num, Module Type, Param Len, Params y, Opt Size) 
(* Calc IS starting now ~ ~ - ' *- _ ^ 

(* Wait for the first data byte in DataMod to become zero 

(* the first data byte is located at the address in Data_Address 

GOSUB 100 \(* wait for calc to send ready 

(* 

(* Calc is running. Send it data 

REPEAT 

RUN Lock (Data Addr) 

(* load DataMod with data 

FOR i«2 TO 6 

INPUT "Enter a number (1..255), or to stop):". Num 

POKE Data Addr+i,Num 

NEXT i 

?S5F,«^?^S-M^r"^^!^ \(* »ark the module "ready for operation" 

GOSUS 100 \(* wait for calc to indicate ready 

PRINT "Sum of squares is "; PEEK (Data Addr+7)'^256+PEEK(Data Addri;+8) 

RUN UnLock (Data Addr) " - 

INPUT "More calculations? (Y,N):",NY 

UNTIL NY«"N" OR NY-"n" 

INPUT "Shut Down Calc Module? (Y,N):",NY 

IF NY-"Y" OR NY="y" THEN 

RUN Lock(Data_Addr) 
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POKE Data Addr+1,2 \(^ command for stop 

WHILE PEEK (Data Addr+1)<>0 DO ^ 

SHELL "SLEEP 2"~ 

ENDWHILE 

RUN UnLock(Data Addr) 

RUN SUnLink (HeaSer Addr) 

ENDIF 

END 



100 (* Wait for the status byte in DataMod to 

C'^ indicate ready 

WHILE PEEK (Data Addr+1)<>0 DO 

SHELL "SLEEP 2"~ 

ENDWHILE 

RETURN 
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COLUMN FIVE 



MORE ABOUT LOCKING 

Last month I discussed shared data modules, 
and demonstrated a locking method which 
could be used to permit only one process at 
a time to access a data module, or, for 
that matter, any shareable resource. 

The locking protocol I demonstrated 
last month has two serious problems. One 
is only a problem for those who, like most 
of us, can only run more than one process 
by sharing a processor between several pro^ 
cesses. The other problem limits the use- 
fulness of concurrent processes. Both 
problems have solutions. 



which process runs and for how long). It 
is your job to prevent a certain process 
from ever getting the lock. You may run 
any mix of programs you like any way you 
like except that the process you are trying 
to prevent from getting the lock must be 
allowed to run every now and then. If It 
Is possible to prevent that process from 
ever getting the lock, there is lockout. 
The sequence of events that demonstrates 
that lockout is possible for the algorithm 
I gave last month 1s: Two processes are 
running, A and B. Both processes are simple 
programs which just get the lock then 
release It again and again. Either process 
could be locked out, but the "execution 
sequence" in figure Figure 1 only demon- 
strates that process B can be locked out. 



The locking algorithm I demonstrated 
last month used a technique called "busy 
waiting." This is usually the easiest way 
to make a process wait until something hap- 
pens, but It wastes processor cycles. I 
tried to reduce the amount of time wasted 
in the locking module as much as possible 
by putting a "sleep" In its wait loop, but 
the solution I gave was, nevertheless, 
inefficient. If waiting for the lock uses 
processor time, even very slowly, all you 
have to do 1s 1 Ine up enough processes 
waiting for the lock and you can slow the 
computer down to a crawl . You might think 
that you could always make the waiting pro- 
cesses as cheap to run as necessary by put- 
ting a longer sleep into the wait loop, but 
1 f the s 1 eep 1 s made very 1 ong , there may 
be a significant time during which the lock 
is off and the all the processes which want 
it are sleeping. If the goal is perform- 
ance, (using performance in the same sense 
as "high performance car") It Is not good 
to leave a scarce resource like the lock 
unused for any length of time. The goal Is 
to design an algorithm which allows waiting 
processes to be completely idle until the 
lock is available, then awakens one process 
and gives it the lock. 

I f each process 1 s runn 1 ng on Its own 
processor, the processor running a waiting 
process has nothing better to do than zip 
around the wait loop. Some people think 
busy waiting is bad even then. I tend 
toward the opposite extreme. The problems 
with busy waiting are obvious, the alterna- 
tives have trickier problems. The Issues 
involved in choosing a busy waiting algor- 
ithm over a more sophisticated one are much 
like those involved in choosing a bubble 
sort over one of the flashier sorting 
algorithms, that is, for a small problem 
the simple algorithm will do fine. 

The other problem with the locking 
algorithm I gave is that It permits "lock- 
out." ie. a process can wait forever with- 
out ever getting the lock even when no oth- 
er process holds the lock forever. If 
there will seldom be a process waiting for 
the lock, lockout isn't a big problem, but 
for locks that usually have a process or 
more wailing for them lockout is an impor- 
tant consideration. 

It is tricky to detect lockout in an 
algorithm, but here are the basic rules for 
finding it: Imagine that you are control- 
ling the computer's dispatcher (deciding 
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A: lock 




B: try to lock 
A: unlock 






A: lock 




B: try to lock 




A: lock 




etc. 




Figure 1: Execution 


Sequence 


for Lockout 





You see that by allowing process A to run 
long 'enough so that can get the lock again 
each time it releases It I can shut process 
6 out completely. This may seem unfair, 
but it shows that the algorithm permits 
lockout. Murphy's law certainly dictates 
that If It is possible to prevent a process 
from ever getting the lock (and you want it 
to get the lock), the Improbable execution 
sequence which leads to lockout will happen 
at the worst possible moment. This is one 
of the kinds of problem that cause strange 
behavior in complicated systems. 

There are many ways to do locking that 
don't use busy waiting or have deadlock. I 
am not going to discuss these tricks this 
month, but I will leave you with two hints. 
The OS-9 SEND service request offers an 
alternative to busy waiting. Locking can be 
done without deadlock by using any of sev- 
eral algorithms including one called the 
Doorman Algorithm. 



GETTING A GOOD '•MIX" 

The standard use for multiple processes is 
to make maximum use of a processor when the 
work to be done involves a lot of waiting 
for outside events, such as terminal Input. 
A process could spend most of Its time 
waiting for input from a terminal, and del- 
egate any major work to child processes. 
This way the program would almost always be 
ready to accept input from the terminal , 
even when some previous piece of work was 
still in progress. Using a special process 
to print a screen is a particularly apt use 
of this principle. There is really no rea- 
son why someone should have to wait for a 
print request to complete before continu- 
ing, and there is usually no need for the 
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process that is doing the printing to com- 
municate with its parent process. The pro- 
cess that is driving the printer spends 
most of its time waiting for the printer, 
and the process that is responsible for the 
screen is. very likely, spending most of 
its time waiting for input from the termi- 
nal . These tasks can be in progress at the 
same time with almost no effect on one 
another. When one process is waiting for 
something, the other process can run with- 
out interference. With tasks like printing 
and screen handling, the computer wi.ll 
spend most of its time with both processes 
waiting. 

Some programs run well together, other 
programs interfere badly with each other. 
Finding good sets of programs to run at the 
same time, and adjusting their priorities 
so they all will run as fast as possible is 
called finding a good "mix." Tuning hard- 
ware and software so a single program can 
run as fast as possible is a complicated 
job. but choosing groups of programs which 
will run well together, and tuning the sys- 
tem so the groups will run as fast as pos- 
sible is more of a black art. I like to 
keep my personal computer rather lightly 
loaded (no more than two or three processes 
active at a time), but it is good question 
just how much time a computer should spend 
waiting. If you give the machine so much 
work to do that it never has to wait, each 
process will run slowly. A computer that 
has no resources in reserve is said to be 
saturated. 

Consider the case of a program which is 
reading from the terminal. Usually, in a 
saturated computer, there are several pro- 
cesses waiting for processor time at any 
moment. The process waiting for the input 
character will have to wait for at least 
one process, maybe several, to have their 
turn before It will get a chance to run. 
If each process gets a turn one tenth of 
second long, and there are an average of 
two processes waiting to run, then a pro- 
cess will take about two tenths of a second 
to respond to a simple keystroke. That 
comes to 5 characters pBr second, or 300 
characters per minute. For perspective, my 
terminal repeats at 10 characters per sec- 
ond. 

Fortunately, programs running under 
OS-9 don't actually do any I/O. OS-9 Is 
arranged so that input and output are done 
by OS-9 rather than by user programs. The 
device drivers are responsible for all I/O. 
OS-9 always gives very fast service to 
device drivers. Almost anything will be 
interrupted to allow a device driver to 
deal with input or output. Some device 
drivers have a reservoir for 100 (or so) 
characters which they can save up and give 
to a process In a burst next time the pro- 
cess is started. 

For the best performance a computer 
should be kept Idle most of the time, that 
way it will Immediately jump on any work 
you give it. It would be nice to have 
enough money to buy overpowered computers 
80 there would be lots of idle time and 
excellent performance, but If money Is a 
concern you have to strike a compromise 
between getting fast response, and getting 
the maximum amount of work out of your 
machine . 



It is possible to speed up important 
processes by changing their priority. The 
heavier the load on a computer, the more 
important it is to fuss with priorities. 
An edit session, a listing to the printer, 
and an assembly can share the machine very 
nicely if the priorities are properly set. 
The edit session is interacting with an 
impatient human, so it should have a high 
priority assigned to It. Since editing 
usually involves a lot of dead time while 
the human doing the editing stares at the 
screen, the editor will actually use very 
little processor time. The process that is 
printing 1s very much the same story. It 
Isn't Interacting with a human, but even a 
200 character per second printer Is slow by 
computer standards. The process that Is 
driving the printer should be given an 
intermediate priority so it will be able to 
run the printer at a good clip without 
interfering to any great extent with the 
edit process. The assembly shbuld be given 
a very low priority. Assemblies are the 
type of thing that will use a lot of pro- 
. cesser time if they are allowed. Even if 
it is given a low priorit/, the assembly 
will get time that the other processes 
don't want, so since both will usually be 
waiting for something, the assembly will 
get plenty of time. 

Most Pusiness programs, as well as com- 
pilers, assemblers, and disk utility pro- 
grams, spend a lot of time waiting for the 
disk to do something. The sound of a disk 
clucking and buzzing is a pleasant busy 
sound, but it actually signifies wasted 
time. While the disk is doing mechanical 
things like starting, seeking, loading the 
head, and even turning, some program Is 
likely to be waiting. OS-9 makes some 
effort to speed disk access, but with sev- 
eral processes wanting to access the same 
disk the problem ls more than a small opei — 
ating system can handle. There are stan- 
dard tricks for reducing the amount of time 
a program spends waiting for the disk 
drive. The easiest of these for a regular 
user to get at Is the use of large buffers. 
Most programs that access the disk will run 
faster if they are given enough storage so 
they can read and write large blocks of 
data. If you want to hear some y/ery busy 
noises from your drives, start a COPY with 
only a little bit of memory, then do a DIR 
for a large directory on the same disk you 
are COPYing on. The disk drive will chuck- 
le madly as It shuttles back and forth from 
directory to file In an attempt to serve 
both the copy program and the DIR command. 
Switching from file to file on a disk (even 
a Winchester) is slow. The Pest way to 
deal with this Is to avoid the problem by 
not running more than one program accessing 
a particular drive at a time. It will be 
obvious If there is a problem. If programs 
are run In the wrong combinations, they 
will run very slowly, and the disk will 
sound very active. If you have to make the 
best of a bad mix. give processes as much 
memory as you can. Well designed programs 
can use extra storage to cut down disk 
usage, or to transfer (read or write) more 
data for each turn they get . 
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AN ASSEMBLY LANGUAGE PROGRAM 
WHICH SETS PRINTER OPTIONS 

I just installed a new printer on my sys- 
tem» an Okidata Micro! ine 92 (nice print- 
er). I used to set the options on my MX80 
with a group of procedure files. An exam- 
ple would be the file called Comprint which 
contained the command "display Of >/p". It 
would have been possible to set the printer 
to compressed printing mode by typing the 
display command instead of invoking the 
procedure file by typing /dO/compr 1nt , but 
I can never remember the Epson control 
codes. Installing a new printer seemed 
like a good excuse to find a better way of 
setting the printer options. The program 
POpt is the first complete assembly lan- 
guage program I have published here. I 
hope you find it as useful as I do. 

POpt doesn't do anything technically 
exciting, but it is a fairly simple assem- 
bly language program which includes most of 
the elements found in assembler programs, 
I am going to go through the interesting 
points of the program moving generally from 
the beginning to the end. 

The NAM and TTL statements in the first 
two lines of the program are purely cosmet- 
ic. They provide information which the 
assembler puts in the page headings. The 
block following those two lines 1S the 
introductory comment for the program. All 
comments might be considered cosmetic, but 
although they don't generate any code, I 
think of them as essential parts of assem- 
bly language programs. Any line with an 
asterisk in column one is a comment; the 
box I draw around the comment is just to 
make it look nice. 

If you are looking at the output of the 
assembler, the two lines after the intro- 
ductory comment are IFPI and ENDC . In the 
original source there is a line between 
these, "use /dO/def s/def si ist " , which calls 
in a list of USE commands which make files 
containing all the system definitions part 
of the program. These definitions help 
make the rest of the program more readable. 
The words Prgrm+Objct would have to be 
replaced with the much less understandable 
$11 if the system definitions, or some oth- 
er similar set of definitions, weren't 
included in the program. Throughout the 
rest of the program I used the symbols 
defined in the definitions files (and a few 
additional SET commands in the program 
itself) whenever I could. The IFP1/ENDC 
which is wrapped around the use statement 
prevents the extra files from being read on 
the second pass the assembler takes through 
the file. No statement in the system defi- 
nitions defines any memory so there is no 
reason for the assembler to read It on both 
the first and second passes; not reading It 
during the second pass saves a good deal of 
time, and prevents the lines in the defini- 
tions from being included In the program's 
line numbering. The lines used from the 
definitions files don't print both because 
they aren't read on the second pass (when 
output is generated), and because the first 
line in the definitions file is the assem- 
bly directive OPT -1 which directs the 
assembler not to print anything until it 
encounters the OPT 1 directive. The defi- 
nitions files I routinely Include in assem- 
blies are listed In table Table 1. 



Table 1: Definitions files 

routinely included in 
assembl ies 

0S9Defs 

0S9SYsDefs 

OS9lODefs 

0S9RBFDefs 

0S9SCFDefs 



There are a lot of symbols in all those 
files; a program with the full set of defi- 
nition files generally needs to be assem- 
bled in a region of at least 24K to accom- 
modate the large symbol table. If you want 
to use your memory more economically, cre- 
ate a stripped down definitions file with 
only the definitions you expect to use, and 
use it instead of the standard files; but 
be prepared to scrap your file and build a 
new one if you get a new version of the 
operating system. Level One and Level Two 
definitely have different definitions, and 
1f you dig around deep enough in the oper- 
ating system, it is unwise to count on 
things staying fixed even from version to 
version. 

A few lines down from the ENDC is the 
MOD statement. This statement generates 
the OS-9 module header, a block of data 
which OS-9 needs. The fields in the module 
header are: 

• PROGRAM LENGTH 

Trying to fill In a number here would 
be foolish. The assembler can figure 
out the length of the module for you. 
The symbol PgmLen Is defined in the 
last line of this program. 

• SYMBOL USED FOR PROGRAM NAME LOCATION 

This isn't the program name itself, 
but the name you choose to assign to 
the location containing the name. I 
like the name "Name" for that loca- 
tion. The program's name is usually 
placed close to the module header, but 
It can be placed elsewhere in the 
module if it is convenient for you to 
do It that way. 

• MODULE TYPE 

I like to define the module type as a 
symbol before the MOD statement and 
just put the symbol here. The module 
type tells OS-9 what kind of thing to 
expect this module to do. This module 
is a program (not a subroutine or 
data), and it consists of object code 
(not data or some sort of Intermediate 
code ) . 

• REVISION 

This field contains two types of 
information. It indicates whether the 
module is reentrant, usable by several 
different users at the same time, and 
gives the revision number of the pro- 
gram. Most well written programs are 
reentrant, so, since OS-9 uses reent- 
rant modules more efficiently than 
non-reentrant modules, most programs 
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should be labeled reentrant. The 
revision number is used when e module 
is loaded from disk to determine 
whether the module should replace a 
module by the same name already in 
memory. A module with a higher revi- 
sion number will replace a module with 
a lower number. This is particularly 
useful if you want to override a mod- 
ule which has been placed in ROM. 
Unless you want to supersede a module 
in memory the revision should be 1. 



ENTRY POINT 

The name 
instruction 
insert a 
instruction 
name on it. 
of typing 
tions before 
a program. 



assigned to the first 

in the program. I usually 

1 ine before the first 

in the program with this 

This saves a little bit 

if I want to add instruc- 

the first instruction in 



• MINIMUM AMOUNT OF PERMANENT STORAGE 
REQUIRED 

The amount of storage the program will 
need in addition to the storage used 
for the module itself. This number, 
like the program length, can be cal- 
culated by the assembler -- note the 
MemSize equ . a few 

The line after the MOD statement tells the 
assembler to reserve space for one byte of 
storage. The next two lines reserve 255 
more bytes. The total memory requirements 
of this program are one byte for the print- 
er's path number, and 255 bytes for the 
stack. The stack probably doesn't need to 
be that large for this simple program, but 
OS-9 is going to allocate memory in 256 
byte units even on a level I system, so X 
played it safe and squandered the memory on 
the stack. The results of allocating too 
little space for the stack are very unplea- 
sant , 

The equate after the rmb for the stack 
uses the -." special symbol which means 
the current offset in the data definitions. 
This is an easy way to get the assembler to 
tell us how much storage the program will 
need for use in the MOD statement. 

The next two lines are the module's 
name (pointed to by the module name field 
in the module header), and the version num- 
ber. The module name must be defined with 
a FCS statement. This type of data defini- 
tion closes the string It is defining by 
setting the high order bit on in the last 
byte -- -t" is $F4 instead of $74. This 
lets OS-9 know where the end of the name 
is. The byte after the name is by conven- 
tion the version number of the program. 
Some utility programs display this number, 
but it is optional. Nothing awful will 
happen if you start right in with data or 
program after the program name. 

The version number is the last overhead 
until the very end of the program. The 
fee's and fob's for the next 40 or so lines 
define constants needed in the program. 
About the only interesting thing about them 
is that each of the strings defined with a 
fee is followed by fob C$CR» a carriage 
return. At first it looks like I could 
have saved space by using one <CR> for all 
the strings, but it turns out that the 
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extra code needed for that approach uses 
more memory than the extra carriage 
returns. 

The program scans the parameter string, 
and if certain characters are found, sends 
character strings to the printer. There 
are three phases: first the input length, 
in D, is checked. If it is one (or lower) 
there is no parameter string; in this case 
display a menu of options. Second, scan 
the parameter string for the character "/" 
which denotes a device name. If there is a 
device name in the parameter, open that 
device as the printer, otherwise open the 
device /P. Third. scan the parameter 
string again ignoring any characters In a 
device name. Translate each character to 
upper case and compare the translated char- 
acter to each significant character. Each 
time a significant character is found, 
transmit the appropriate character string 
to the printer, and send a line to the 
standard output path describing what has 
been done . 

There are a couple of simple tricks 
which are useful while scanning the parame- 
ter string. The shell always terminates 
the parameter string with a carriage 
return. This lets me terminate the scan 
when I encounter a carriage return instead 
of having to count bytes. Data bytes may 
have the parity bit on or off . I remove 
the parity bit with "anda #$7?," If the 
parity bit is left on, twice as many com- 
parisons need to be done. For example, "a*' 
could be $61 or $E1. In this case, I 
thought it would be best to treat both 
upper and lower case characters as the 
same. The easiest way to do this is to 
translate all lower case letters to upper 
case (or vice versa if you like). Once you 
determine that a character is an upper case 
letter It can be translated to a lower case 
letter by subtracting $20 from it, or and- 
ing %11011111 with it. 

There are two sections of this program 
responsible for output. Commoni writes 
strings two bytes long to the printer. It 
uses the I$Write service request which 
writes a specified number of characters 
without any editing. There Is nothing spe- 
cial about two bytes; It Is just the length 
of the longest control string I wanted to 
be able to send to the printer. I padded 
the shorter control strings to two bytes by 
adding a $00. a null, to them. Common2 
writes up to 80 characters to the standard 
output path. Common2 uses the I$WritLn 
service request which treats the carriage 
return as a special case. When it encoun- 
ters a carriage return it does whatever the 
path descriptor is set up to do on end of 
line (normally send <CR><LF>) and returns. 
This means that by terminating each string 
to be written by Common2 with a <CR> I make 
it unnecessary to know the length of any of 
the strings. 

This program ends in either of two 
places. If there are no errors, after the 
second scan the program branches to Exit 
which clears the -carry bit in the condition 
code and performs the F$Exit service 
request returning control to OS-9. If 
there is an error, control goes to ErrXit 
which sets the carry bit and returns con- 
trol to OS-9. You might expect that the 
best way to set or clear the carry bit in 



the condition code register is with the 
andcc and orcc instructions. Those 
instructions certainly are able to turn the 
carry bit on and off, but the COM instruc- 
tion turns the carry bit on faster (and the 
CLR instruction turns it off faster) than 
the obvious instruction. Whenever the A or 
B accumulator is free, it is fastest to set 
or clear the carry flag by playing with the 
accumulator. 

At the very end of POpt there are two 
final lines of overhead. The EMOD direc- 
tive causes the assembler to generate a 
Checksum for the module which is used when 
this program is run to make certain that 
the module is valid and undamaged. The 
line with "PgmLen equ *" calculates the 
length of the module for use in the MOD 
statement at the very beginning of the mod- 
ule. 



THE OS-9 USER'S GROUP 

An OS-9 User's Group was formed last sum- 
mer. I couldn't say it's thriving, but it 
is coming along. The club has a telephone 



bulletin board, and lots of dreams. It 
isn't going to go anywhere unless plenty of 
OS-9 users join it. Membership is $25 for 
individuals (payable to OS-9 Users Group 
c/o Terry Straehley 1005 RoDle Lane, Santa 
Barbara CA 93103). I strongly suggest that 
all OS-9 users join the group. Even with 
the relatively small membership the group 
now has, a lot of interesting information 
passes through the bulletin board. If we 
all join, this group could become a great 
resource . 



THE FUTURE OF THIS COLUMN 

There is enough material for another six 
months or more of columns about concurrent 
processes, but I am going to move on to 
some other subjects for a while. It seems 
there are a great many new OS-9 users out 
there, some of whom heive written to me ask- 
ing for help with the fundamentals of the 
system. The program this month is a first 
attempt to help these people. I'll try to 
devote at least part of this column to OS-9 
basics for the next few months. 
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00001 
00002 
00003 
00004 
00005 
00006 
00007 
00008 
00009 
00010 
00011 
00012 
00013 
00014 
00015 
00016 
00017 
00018 
00019 
00020 
00021 
00022 
00023 
00024 
00025 
00026 
00027 
00028 
00029 
00030 
00031 
00032 
00033 
00034 
00035 
00036 
00037 
00038 
00039 
00040 
00042 
f^^0043 
'' '^044 
■!45 
V j46 D 
:j047 

00048 D 

00049 D 
00050 
00051 
00052 
00053 
00054 
00055 
00056 
00057 
00058 
00059 
00060 
00061 
00062 
00063 
00064 
00065 
00066 
00067 
00068 
00069 
00070 
00071 
00072 
00073 



NAM 
TTL 



POpt 
Change 



Printer Setup 



Page 001 



Options for ML 93 



* 

* 
* 
■k 
* 

* 
* 
* 
* 
* 

ft 
* 
* 
■k 
* 
* 
* 
* 
* 

* 
* 



Printer 
c 


2 

7 

5 
6 
8 



Setup Options 
Correspondence 



Ten CPI 
12 CPI 
17 CPI 

Double Width 
Five CPI 
Six CPI 
Eight CPI 



Quality 



Characters 



reset to initial conditions 

Lead in for alternate path name. Default 
is /p. The path name must either be the 
last parameter, or separated from the next 
parameter by a delimiter. 



The options are 
POpt is run. If 
is presented. 



specified as parameters when 

no options are specified, a menu 



0011 
0081 
0000 
0000 
OOFF 
0001 
0100 
OOOD 
0011 
0001 
0012 
0014 



0015 
004A 
004B 
007F 
0080 
00B4 
00B5 
00E2 
00E3 
OlOB 
OlOC 
0130 
0131 
0150 
0151 
015E 



Examples : 
popt 



-> 
— > 
-> 



.. rc2 

Printer Reset 

Correspondence Quality Printing 

Print Density twelve characters per inch 



— > 
-> 
-> 

You _ 
sides 



popt r6 /pi 
Printer Reset 

Print Density six characters per inch 

{output was directed to the printer at 

can put the print options on either or bo 

of the device name 



(f 



popt re /pi is the same as popt r /pi c 



it 

it 

Vt 

ii 
-k 



it 



87CD04BA 



50AF70FA 
01 

2F50 
OD 

-krfi-kit-kicit: 

5072696E 

OD 

5072696E 

OD 

5072696E 

OD 

5072696E 

OD 

5072696E 

OD 

5072696E 

OD 

A36F7272 

OD 

5072696E 

OD 



Type 
Revs 

PrtPthN 
StackSz 

Hemsize 

Name^ 

Edition 

StdOut 

DPrtNam 



IFPl 

ENDC 

set 

set 

MOD 

rmb 

set 

rmb 

equ 

fcs 

fob 

set 

fee 

fcb 



Prgrro+Objct 

ReEnt+1 

PgmLen , Name , Type , Revs , Ent ry , MemSize 

255 
StackSz 



/POpt/ 

1 
1 

C$CR 



space for stack 



Number of Standard Output Path 
Default Printer Name 



Responses for each printer option 
MsgSCPI 
Msg6CPI 



set 



fee /Print density 

fcb C$CR 

fee /Print density 

fcb C$CR 

KsgSCPI fee /Print density 

fcb C$CR 

MsglOCPI fee /Print density 

fcb C$CR 

Msgl2CPI fee /Print density 

fcb C$CR 

Msgl7CPI fee /Print density 

fcb C$CR 

MsgCQ fee /Correspondence Quality Printing/ 

fcb C$CR 

MsgRst fee /Printer Reset/ 

fcb C$CR 



five characters per inch ( 
six characters per inch (d 
8.5 characters per inch (d 
10 characters per inch (no 
twelve characters per inch 
17 characters per inch/ 



30 



OS-9 User Notes Volume I 



Microware OS-9 Assembler 2.1 08/05/8A 23:06:37 
POpt - Change Printer Setup Options for ML 93 



Page 003 



001A2 
'"*0143 
00144 
00145 
00146 

r -47 

(. 48 

00149 

00150 

00151 

00152 

00153 

00154 

00155 

00156 

00157 

00158 

0159 

-J 160 

l':}161 

00162 

'■'0163 

00164 

0O165 

00166 

00167 

00168 

00169 

00170 

00171 

00172 

00173 

00174 

00175 

00176 

50177 

0D178 

'0179 

.-D180 

.'^0181 

82 

.83 

>0184 

50185 

00186 

00187 

00188 

00189 

00190 

00191 

00192 

00193 

00194 



No alternate printer path found 



* 



0343 
0343 
0347 
0349 
0349 



308DFCCB 
20ED 



3536 

* 

* 
* 



LooplD 



LooplE 



leax DPrtNam.PCR 

bra Loopll Open the default printer path 



puis D,X,Y 



restore 



Loop2 scans the parameter string for 

frinter control options. If an option is 
ound the corresponding subroutine is 
called. 



A 



■k 



034B Loop2 

034B 

034D 
034F 
0351 
0353 
0355 

0357 ._.,_ ,. , ,_ 

0359 102700EO Ibeq SkipPN Yes; Ski|> over the path name 



A680 
847F 
810D 
2738 
8120 
23F4 
812F 



Ida 

anda 

cmpa 

beq 

cmpa 

bis 

cmpa 




clear parity bit 
<CR>? 

control character? 

yes; loop 

start of a path name? 



035D 
035F 
0361 
0363 
0365 
0367 



* 
* 

A 

8161 
2506 
817A 
2202 
8020 



Translate lower to upper case if 
necessary. 

cmpa # ' a 



bio 
cmpa 
bhi 
suba 



oop21 

#'z 

Loop21 

#$20 



0367 
0369 
036B 
036D 
036F 
0371 
0373 
0375 
0377 
0379 
03 7B 
03 7D 
037F 
0381 
0383 
0385 
0389 



* 

* 

* 

8152 

2724 

8143 

2734 

8130 

2743 

8132 

2751 

8135 

2760 

8136 

276F 

8137 

277E 

8138 

1027008B 

20C0 



Loop21 
Analyse the parameter 



lower to upper case 



-A 

A 

.* 



cmpa 

beq 

cmpa 

beq 

cmpa 

beq 

cmpa 

beq 

cmpa 

beq 

cmpa 

beq 

cmpa 

beq 

cmpa 

Ibeq 

bra 



#'R 
Reset 

enCPI 






vCPI 
iveCPI 



r.6 

SiJ 



xCPI 
'7 

vntnCPI 
'8 

ightCPI 
Loop2 



reset? 

Correspondence quality? 

Ten CPI 

Twelve CPI 

Five CPI? 

6 CPI 

Seventeen CPI 

Eight and a half CPI? 



10195 
S0196 
J0197 
00198 
00199 
00200 
00201 
00202 
00203 
00204 
00205 
00206 
00207 
00208 
00209 
00210 
00211 
00212 
00213 



0386 
038B 
038C 
038F 
038F 
0391 
0395 
0398 
039C 
039F 
03A1 
03A3 
03A3 
03A5 
03A9 
03AB 
03AF 
03B2 
03B4 



5F 
103F06 

3410 

308DFDD8 

17008F 

308DFDB5 

170094 

3510 

20A8 

3410 

308DFDB6 

8D7C 

308DFD82 

170081 

3510 

2095 



Exit 



Reset 



CQ 



clrb set B (return code) to and t 

0S9 F$Exit return to OS-9 

pshs X 

leax CCRst.PCR point at Reset control string 

Ibsr Commonl write it 

leax HsgRst.PCR point at remark 

Ibsr Common2 write it 

puis X 

bra Loop2 go search for next option 

fshs X 

eax CCCQ,PCR 

bsr Commonl 

leax MsgCQ.PCR 

Ibsr Common2 

Euls X 

ra Loop2 
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00074 

00075 

00076 

00077 

00078 

00079 

00080 

00081 

00082 

00083 

00084 

00085 

00086 

00087 

00088 

00089 

00090 

00091 

00092 

00093 

00094 

00095 

00096 

00097 

00098 

00099 

00100 

00101 

00102 

00103 

00104 

00105 

00106 

00107 

00108 

00109 

00110 

00111 

00112 

00113 

00114 

00115 

00116 

00117 

00118 

00119 

00120 



'^' Printer Control Strings 

015F 1B31 CCCQ fcb $lb,'l 

0161 lElF CC5CPI fcb S1E,$1F 

0163 ICIF CC6CPI fcb S1C,$1F 

0165 IDIF CC8CPI fcb $1D,$1F 

0167 lEOO CCOCPI fcb $1E,0 

0169 ICOO CC2CPI fcb $1C,0 

016B IDOO CC7CPI fcb $1D,0 

016D 1800 CCRst fcb $18,0 

^ The Menu 



016F 4E6F206D 

OlAO OD 

OlAl A92FAF20 

OIBA OD 

OIBB 50AF707A 

OlEl OD 

01E2 2052202D 

01F8 OD 

01F9 20A3202D 

021 A OD 

021B 2035202D 

02 A 1 OD 

02A2 2036202D 

0267 OD 

0268 2038202D 
029A OD 
029B 2030202D 
02C0 OD 
02C1 2032202D 
02E9 OD 
02EA 2037202D 

0315 OD 

0316 Entry 

* X points to the 

* Y points to the 

'^ The last charact 

^ D contains the 1 



ErrMsgl 

ErrMsg2 

Menul 

Menu2 

Menu3 

MenuA 

Menu5 

Menu6 

Menu7 

Menus 

Menu9 
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Set correspondence quality 

Five CPI 

Six CPI 

Eight CPI 

Ten CPI 

Twelve CPI 

Seventeen CPI 

reset printer 



fee /No more than 127 bytes of parameters are 

fcb C$CR 

fee .1/0 error on printer path. 

fcb C$CR 

fee /POpt accepts the following parameters:/ 

fcb C$CR 

fee / R - Reset the printer/ 

fcb C$CR 

fee / C - Correspondence quality print/ 

fcb C$CR 

fee / 5 - Print at five characters per inch/ 

fcb C$CR 

fee / 6 - Print at six characters per inch/ 

fcb C$CR 

fee / 8 - Print at eight and a half character 

fcb C$CR 

fee / - Print at ten characters per inch/ 

fcb C$CR 

fee / 2 - Print at twelve characters per inch 

fcb C$CR 

fee / 7 - Print at seventeen characters per i 

fcb C$CR 



start of the parameter area. 

end of the parameter area, 

er in the parameter area is a <CR>. 

ength of the parameter area. 



0316 
031A 
031E 
0322 



10830001 
10230137 
10830080 
102A017E 



cmpd #1 

Ibis Menu 

cmpd #128 

Ibhs Errorl 



Check length of parameter area 
if there is nothing there; Dis 
It*s hard to deal with paramet 
^^S^' parameter area too long 



00121 
00122 
00123 
0012A 
00125 
00126 
00127 
00128 
00129 
00130 
00131 
00132 
00133 
0013A 
00135 
00136 
00137 
00138 
00139 
OOIAO 
OOlAl 



* Search parameters for output device overide'J^ 



0326 3A36 
0328 

0328 A680 
032A 8A7F 
032C 810D 
032E 2713 
0330 812F 
0332 26FA 
033A 301F 

0336 

* 

it 

Vt 

0336 8602 
0338 103F8A 
033B 102501AF 
033F 9700 
03A1 2006 



Loopl 



pshs D,X,Y 



Ida 

anda 

cmpa 

beq 

cmpa 

bne 

leax 



//$7F 
ooplD 



LoopJ 
"1,X 



Loopll 
Open alternate printer path 



Ida 

0S9 

Ibcs 

sta 

bra 



#Write. 

I$0pen 

Error2 

PrtPthN 

LooplE 



save everything 

clear parity bit 
<CR>? 

start of path name? 

back up one to / 



-* 

* 
-* 



save the path number 
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Page OOA 



00214 

00215 

00216 

00217 

00218 

00219 

00220 

00221 

00222 

00223 

00224 

00225 

00226 

00227 

00228 

00229 

00230 

00231 

00232 

00233 

00234 

00235 

00236 

00237 

00238 

00239 

00240 

00241 

00242 

00243 

00244 

00245 

00246 

00247 

00248 

00249 

00250 

00251 

00252 

00253 

00254 

00255 

00256 

00257 

00258 

00259 

00260 

00261 

00262 
00263 
00264 
00265 
00266 
00267 
00268 
00269 
00270 
00271 
00272 
00273 
00274 
00275 
00276 
00277 
00278 
00279 
00280 
00281 
00282 
00283 
00284 
00285 



03B6 
03B6 
03B8 
03BC 
03BE 
03C2 
03C4 
03C6 
03C8 
03C8 
03CA 
03CE 
03D0 
03D4 
03D6 
03D8 
03DB 
03DB 
03DD 
03E1 
03E3 
03E7 
03E9 
03EB 
03EE 
03EE 
03F0 
03F4 
03F6 
03FA 
03FC 
03FE 
0401 
0401 
0403 
0407 
0409 
040D 
040F 
0411 
0414 
0414 
0416 
041A 
041C 
0420 
0422 
0424 

0427 
0427 
0429 
0A2D 
0430 
0432 
0433 
0433 
0435 
0439 
043C 



3410 

308DFDAB 

8D69 

308DFCF3 

8D6F 

3510 

2083 

3410 

308DFD9B 

8D57 

308DFD0F 

8D5D 

3510 

16FF70 

3410 

308DFD80 

8D44 

308DFC2E 

8D4A 

3510 

16FF5D 

3410 

308DFD6F 

8D31 

308DFC51 

8D37 

3510 

16FF4A 

3410 

308DFD64 

8D1E 

308DFCFF 

8D24 

3510 

16FF37 

3410 

308DFD4B 

8D0B 

308DFC60 

8D11 

3510 

16FF24 



TenCPI 



9600 

108E0002 

103F8A 

255C 

39 

8601 

108E0050 

103F8C 

39 

* 

* 
*_ 



TwlvCPI 



FiveCPI 



SixCPI 



SvntnCPI 



EightCPI 



Commonl 



CoiniDon2 



pshs 

leax 

bsr 

leax 

bsr 

Euls 
ra 

fshs 
eax 
bsr 
leax 
bsr 
puis 
Ibra 

?shs 
eax 
bsr 
leax 

bsr 

fuls 
bra 

pshs 
leax 
bsr 
leax 
bsr 
puis 
Lbra 

fshs 
eax 
bsr 
leax 
bsr 
puis 
lbra 

?shs 
eax 

bsr 

leax 

bsr 

?uls 
bra 



Ida 
Idv 
0S9 
bcs 

rts 

Ida 
Idv 
0S9 

rts 



CCOCPI.PCR 

Connonl 

MsglOCPI.PCR 

Coiainon2 

X 

Loop2 



CC2CPI,PCR 

Commonl 

Msgl2CPI,PCR 

Coinmon2 

X 

Loop2 



CC5CPI,PCR 

Commonl 

MsgSCPI.PCR 

Common2 

X 

Loop2 



CC6CPI,PCR 

Commonl 

Msg6CPI,PCR 

Common2 

X 

Loop2 



CC7CPI,PCR 

Commonl 

Msgl7CPI,PCR 

Coi!QDon2 

X 

Loop2 



CC8CPI.PCR 

Commonl 

Msg8CPI,PCR 

Common2 

X 

Loop2 



PrtPthN 

I$Write 
Error2 



//StdOut 

#80 

I$WritLn 



Printer Path Number 
length 

I/O error on printer path 



output path for remarks 
max length of strings 



Skip 



0A3D 
043D 
0A3F 
OAAl 
0443 
0447 
0449 
044D 
044F 
0453 



A680 

847F 

810D 

1027FF44 

8120 

1027FEFE 

812C 

1027FEF8 

20E8 



over alternate printer path name 
SkipFN 



Ida 

anda 

cmpa 

Ibeq 

cmpa 

Ibeq 

cmpa 

Ibeq 

bra 



,X+ 

kiF 

#C$CR 

Exit 

#C$SPAC 

Loop2 

Loop2 

SkipPN 



<CR>? 

yes; done 

<space>? 

end of path name 

end of path name 
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Page 005 



00286 


0455 


Menu 








00287 


0455 308DFD62 




leax 


Menul,PCR 




00288 


0459 8DD8 




bsr 


Cominon2 




00289 


045B 308DFD83 




leax 


Menu2,PCR 




00290 


045 F 8DD2 




bsr 


Coinmon2 




00291 


0461 308DFD94 




leax 


Menu3,PCR 




00292 


0465 8DCC 




bsr 


Cominon2 




00293 


0467 308DFDB0 




leax 


Menu4,PCR 




0029A 


046B 8DC6 




bsr 


Common2 




00295 


046D 308DFDD1 




leax 


Menu5,PCR 




00296 


0471 8DC0 




bsr 


Cominon2 




00297 


0473 308DFDF1 




leax 


Menu6,PCR 




00298 


0477 8DBA 




bsr 


Comffion2 




00299 


0479 308DFE1E 




leax 


Menu7,PCR 




00300 


047D 8DB4 




bsr 


Common 2 




00301 


047F 308DFE3E 




leax 


Menu8,PCR 




00302 


0483 8DAE 




bsr 


Common2 




00303 


0485 308DFE61 




leax 


Menu9,PCR 




0030A 


0489 8DA8 




bsr 


Common2 




00305 


048B 16FEFD 




Ibra 


Exit 




00306 


ifc »__«_„__„ 








, vt 












00307 
00308 


^ 


End with 


an error 


iz 
^ 












00309 


048E 


Error2 


equ 


A 


Error in printer path 


00310 


048E 3404 




pshs 
Idy 


B 


save error code 


00311 


0490 108E0050 




#80 




00312 


0494 308DFD09 




leax 


ErrMsg2,PCR 


00313 


0498 8602 




Ida 


#2 
I$WritLn 




0031 4 


049A 103F8C 




0S9 




00315 


049D 3504 




puis 
0S9 


B 


recover error code 


00316 


049F 103F0F 




F$PErr 


print error message 


00317 


04A2 200F 




bra 


ErrXit 




00318 


04a4 


Errorl 


equ 
idy 


i< 


Parameter string too 


00319 


04A4 108E0050 




#80 
krrMsgl,PC 




00320 


04A8 308DFCC3 




leax 


R 


00321 


04AC 8602 




Ida 


#2 
I$WritLn 


Error output 


00322 


04AE 103F8C 




0S9 




00323 


04B1 C601 




Idb 


#1 


error code 


0032A 


04B3 


ErrXit 








00325 


04B3 43 




coma 




set carry 


00326 


04B4 103F06 




0S9 


F$Exit 




00327 


04B7 285030 




EMOD 






00328 


04BA 


PgmLen 


equ 


* 





00000 error (s) 

00000 warning (s) 

$04BA 01210 program bytes generated 

SOIOO 00256 data bytes allocated 

524F1 09457 bytes used for symbols 
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OS-9 by Itself does very little useful 
work. You won't find an editor, assembler, 
compiler, spelling checker, or payroll sys- 
tem anywhere on the standard distribution 
disk. That isn't to say that you can't get 
these programs for DS-9, or even that some 
of them aren't sometimes packaged with the 
operating system (Gimix packages Micro- 
ware's editor, assembler, debugger, 
Basic09. and RunB with every OS-9 system), 
but OS-9 can be purchased with no frills, 
and in that form it is essentially useless. 

For an experienced microcomputer user 
with lots of friends using OS-9 and a near- 
by store with a large stock of OS-9 soft- 
ware the task of choosing the right array 
of software could be fun, but for me it was 
frightening. The least expensive software 
I could find cost about fifty dollars a 
crack, and it went up fast from there. I 
didn't know anyone running OS-9, and, 
though there were many computer stores in 
Rochester, the only one which dealt in 6809 
based machines believed strongly (nearly 
exclusively) in TSC software. I gritted my 
teeth and bought what looked good to me. I 
was surprised to find that everything I 
bought was at least OK. In retrospect I 
can see that it wasn't so very surprising 
that I was lucky in my software purchases; 
most of the software for OS-9 is good. 

With OS-9 I got the Microware Editor, 
Assembler, Debugger, and Pascal. I have no 
special love for the Microware Debugger, 
but I still use it because it is the only 
game in town. It usually is packaged with 
OS-9, and it is hard to get along without, 
especially if you do assembly language pro- 
gramming, but I hope Microware feels a 
touch of humiliation each time they send 
out a copy of that program -- it is not up 
to the standard set by their other pro- 
grams. The assembler is unexciting, but it 
does the job. There are other assemblers 
around, but the Microware assembler is the 
standard . 

The Microware Editor is hard to classi- 
fy. It is the only non-screen-oriented 
editor for OS-9 that I know of. It works 
fine as a simple editor, but it might be 
more accurate to call it a simple string 
processing language. The editor features 
multiple work spaces, and a high powered 
macro language which can be used to write 
fairly sophisticated programs. The bad 
side of all this sophistication is that it 
is a little bit hard to use the editor for 
simple things. I have never been able to 
figure out how to copy a range of lines 
without using a disk file as a temporary 
holding place. I don't use the Microware 
Editor very frequently since I got a 
screen-oriented editor, but I got a lot of 
work done on it when it was the only editor 
I had, and I still use it occasionally. I 
should add that some people think editors 
like the Microware editor are better for 
programming than the more word processing 
oriented editors. 

It is hard for me to be moderate in my 
praise for Microware's Pascal. I wish it 
included a debugger, and the procedure for 
linking to external procedures is a bit 
clumsy, but I love it. I use it to develop 



programs for classes where the students use 
DEC Pascal and IBM Pascal and have no com- 
patibility problems. There are enough 
enhancements to make this Pascal useful for 
real applications (such as a PROMPT built- 
in procedure which forces out the contents 
of an output buffer without a carriage 
return). The compiler generates intermedi- 
ate code which can be executed by either of 
two interpreters (one normal, and the other 
supporting large programs by a paging 
arrangement), or translated into efficient 
native code. 

Recently I got Basic09. You may have 
guessed from my comments that I am getting 
to like it even though it is called Basic. 

I have DynaStar, DynaForm, and DynaS- 
pel 1 from Frank Hogg Labs . None of these 
programs are exceptional, but I use them 
all regularly. DynaStar is a screen- 
oriented editor with -which I have typed and 
revised many hundreds of pages. It is best 
at editing documents, but usable for pro- 
grams. I expect the reason the program is 
called DynaStar is that it borrows heavily 
from Wordstar. My mother uses Wordstar, 
and I find that I can help her untangle 
some problems with Wordstar by assuming 
that it is keystroke for keystroke identi- 
cal with DynaStar, I have some small com- 
plaints about DynaStar, but the bottom line 
is that I like it well enough to have spent 
hundreds of hours using it. 

DynaForm is a text formatting/mail 
merge program. It is full of fancy Mail- 
Merge features that I never use. I use it 
to print files with optional page headers 
and trailers, underlining, and bold print- 
ing. A few times I have used its ability 
to generate indexes and a table of con- 
tents. DynaForm doesn't do well when com- 
pared to the high powered text formatting 
packages used on large computers, but I 
don't think it is intended to compete with 
that kind of thing. The thing about Dyna- 
Form that annoys me most frequently is that 
it can't be customized to use the special 
features of my printer. It prints bold 
text by simply printing the bold characters 
three times. DynaStar can be used to imbed 
printer control characters in text, but 
DynaForm only knows one way to print bold 
or underlined text. I also wish it would 
use the standard input and output paths 
instead of allocating special paths. 

DynaStar and DynaForm were written by 
Allan Jost. They show signs of being writ- 
ten by a programmer with a very profession- 
al attitude. They are not loaded with fea- 
tures but they are so reliable that I just 
take them for granted. 

DynaSpel 1 is a spelling checker. I 
need a spelling checker very badly. Some 
people buy computers to run a spreadsheet 
program. I might have bought one to run a 
spelling checker. DynaSpel 1 essentially 
looks up each word in a document In a set 
of dictionaries. Any words that it doesn't 
find are treated as questionable words. 
These words can be fixed, accepted as is, 
or accepted and added to a dictionary. 
DynaSpel 1 isn't as carefully written as the 
programs by Allan Jost ; there is nothing 
major wrong, but the meticulous care isn't 
there. When DynaSpel 1 runs out of space to 
store words in, it spews out pages of 
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"overflow" messages. There is no way to 
riieck the contents of the directory when 
DynaSpell is asking for the name of the 
file to check. When you abort the program 
(with a control C) in order to check the 
directory again, DynaSpel 1 leaves the ter- 
minal's device descriptor in a strange 
state. DynaSpel 1 has most of the features 
commonly found in spelling checkers for 
microcomputers, but it doesn't compare with 
similar programs on larger machines. Maybe 
a spelling checker is one of those tasks 
which needs fast machines with large memo- 
ries. I want a spelling checker which 
helps me correct misspelled words by giving 
me a list of suggested spellings, and a 
built, in thesaurus would be another nice 
touch. Still, I use DynaSpel 1 when it is 
inconvenient to ship my files off the the 
IBM to be checked. It isn't a great pro- 
gram, but it does its job. 

I reviewed DynaCalc a few months ago. 
I still like the program, and it is still 
heavily used. I wouldn't have chosen Dyna- 
Calc as part of my core group of software 
(I mostly program and write with my comput- 
er) but I can imagine people who might not 
need any other program. 



NEW RELEASE OF MICROWARE PASCAL 

I just got release 2.0 of Microware's Pas- 
cal. It is a major revision, including a 
new intermediate code language, a single 
general purpose I -code-to-nat i ve-code 
translator, and new run time support mod- 
ules. I didn't do any careful comparisons 
of the two versions, but I get the strong 
feeling that the new release compiles fost- 
er, and runs faster. The new manual is 
significantly better organized and more 
complete than the old one, but still makes 
no attempt to teach Pascal . Two new stan- 
dard functions have been added: GETCHAR, 
which returns a single character from 
input, and lOREADY, which returns true if 
there is input ready. These new functions 
^inould be useful for interactive applica- 
tions 1 ike editors . 



OS-9 DIRECTORIES 

A directory is a special type of file con- 
taining information about files. It could 
be seen as something like a library's card 
file. It contains the names of files along 
with information about them, especially 
where they can be found. Unlike anything a 
proper library would contain, the entries 
in a directory aren't kept in any particu- 
larly useful order. You can get a format- 
ted listing of the contents of a directory 
with the DIR command. 

OS-9, like UNIX and many other multi- 
user operating systems, supports hierar- 
chies of directories on disk. Directories 
can be used for a number of things, or, If 
you like, largely Ignored. A directory can 
contain any number of other directories in 
adoitlon to normal files. 

Every disk has a root directory on it 
which is created when the disk is format- 
ted, and cannot be done away with. Unless 
you fuss around with INIT and SYSGO the 



disk you boot off of must have a directory 
called CMDS in its root directory. There 
may also be a SYS, and a DEFS directory in 
the root directory on the boot disk when 
you install OS-9. 

You (the user) can create new directo- 
ries with the MAKDIR command. To use the 
command type MAKDIR followed by the name of 
the new directory you want to create: 

MAKDIR /Dl/SOURCE* DIRECTORY 

It has become a convention to use capital 
letters for directories' names. OS-9 
doesn't have any trouble with lower case 
directory names, but it is an easy way of 
reminding oneself which files are directo- 
ries . 

It is sometimes tricky to keep track of 
a library of several hundred (maybe thou- 
sand) files. Multiple direc'tories are a 
major help in organizing files in such a 
way as to maximize the chance of finding 
them again. Long ago I found that I 
couldn't fit all my files on one disk (that 
was a 100K floppy back then). I put each 
major project on .a separate disk. When I 
got disk drives with greater data capacity, 
I found that it wasn't an unadulterated 
good thing. Each disk contained so many 
files that it was a major job to locate a 
file even knowing which disk it was on. I 
worked out naming conventions that made the 
job easier, but they used up the first two 
characters of each file name -- the result- 
ing file names were pretty cryptic. I 
still keep hundreds of files on each disk, 
but my largest directory has about forty 
f i les in 1 t , 

The root directory on a disk I have 
labeled "pascal 1" contains nothing but sev- 
en directories: DIST.SRC, UTIL.SRC, 
SUBR.SRC, BUGS, DEFS, DOC, and PCODE . Each 
of those directory names describes what I 
expect to find 1n them pretty well ( to me 
anyhow). Each directory with programs in 
it contains a directory called DOC which 
contains related documentation. If it 
seems like I have large numbers of directo- 
ries called DOC, it's true. Pretty near 
everything needs documentation. Sometimes 
I find that a directory begins to get out 
of control . Projects that I expect to need 
about ten files have a way of expanding to 
forty or fifty files. A project like that 
really belongs in a directory of Its own, 
so I create a new directory in the directo- 
ry that contains tne files for the project, 
and move all the files that are part of 
that project into the new directory. 

Any file can be accessed by giving its 
f ul 1 name, e.g. , 

/D1/UTIL.SRC/DFIX/Compacter would denote 
the file Compacter in the directory DFIX 
which is In the directory UTIL.SRC in the 
root directory on disk D1. but that's more 
typing than I would choose to do except as 
an act of desperation. The most commonly 
used shortcuts are the CHD, and CHX com- 
mands. The CHD command changes the direc- 
tory which is treated as the root directory 
for data. CHX does the same thing for the 
execution directory. 

When OS-9 Is booted the data directory 
is set to the root directory of the boot 
di«k. und the execution directory is set to 
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CMDS in the root directory on the boot 
disk. If you want to use files in the root 
directory on the boot disk, all you need to 
do is give the file name, if you want to 
use files in a directory which is in that 
directory you give the name of the directo- 
ry with the file name, e.g., to get at the 
file 0S9Defs in DBFS in the data directory 
use DEFS/0S9Defs. If the default data 
directory isn't convenient for you, a new 
directory can be selected with the CHD com- 
mand, for example, to change the data 
directory to the root directory on /D1 use 
CHD /D1. The CHX command works the same 
way CHD does, but it effects the execution 
di rectory. 

There are two special entries in every 
directory. The "." entry points to the 
directory itself, and the •' . . " entry 
points to the directory the current direc- 
tory is in, the parent directory. A typi- 
cal use of the ".." entry is to refer to 
sibling directories. When a project gets 
large,* I break it up into a set of directo- 
ries, all in a directory which I set aside 
for the project. If a program needs access 
to the file HexDefs in the directory DBFS 
which is a sibling of the directory SRC 
(where the program is), I can use the 
shorthand name " . . /DEFS/HexDef s" for the 
file. I have found this a good convention 
to stay with. As long as I continue to 
keep related families of files in directo- 
ries that are siblings, the notation 
"../DEFS" will always get me to the appro- 
priate DEFS directory, and "../DOC" will 
always refer to the related Documentation 
directory. 

To experiment with directories, start 
with a disk with some empty space on it. 
and use CHD to set the data directory to 
the root directory. Build some directo- 
ries : 

HAKDIR TESTDl 
MAKDIR TESTD2 
HAKDIR TESTD3 

Make things a little more complicated: 

CHD TESTD2 
MAKDIR TESTD21 
MAKDIR TESTD22 
MAKDIR TESTD23 
CHD TESTD21 
MAKDIR TESTD211 
MAKDIR TESTD212 
MAKDIR TESTD213 
CHD ../TESTD22 
MAKDIR TESTD221 
MAKDIR TESTD222 
CHD ../TESTD23 
MAKDIR TESTD231 
MAKDIR TESTD232 
CHD .. 
CHD .. 



DIR TESTD2/TESTD23 
DIR ./TESTD2/TESTD23 
CHD TESTD2 ; DIR TESTD23 
CHD TESTD2/TESTD23; DIR 

The first two command lines leave the data 
directory at the root directory. The third 
command line moves the data directory to 
TESTD2, and the fourth command line moves 
the data directory all the way out to 
TESTD23. 

It is easy to create new directories, 
but a little involved to delete a directo- 
ry. Perhaps it is a good thing that it 
requires more than one quick operation to 
remove a directory. If a directory with 
files in it is erased, all the files in the 
removed directory will remain on the disk, 
but DS-9 won't be able to locate them. 
Older versions of OS-9 don't have any com- 
mand which will delete a directory. To c^o 
away with a directory with these older ver- 
sions: delete all the files (and directo- 
ries) in the directory, use the ATTR com- 
mand to change the directory into a normal 
file (ATTR <dirname> -d), and delete the 
file that used to be the directory. Be 
particularly careful not to use ATTR to 
change the directory into a regular file 
until the directory is empty. There is no 
easy way to change the file back into a 
directory so you can delete the files in 
it. With the new release of OS-9, the com- 
mand DELDIR can be used to delete directo- 
ries. DELDIR simply automates the steps I 
just went through. 

Directories are an important feature of 
UNIX-like operating systems. They allow 
files to be grouped in manageable clusters, 
and make it easier to handle many concur- 
rent users . 

I am preparing to eat some of the words 
I set down in my first column. I am look- 
ing forward to this with a good deal of 
pleasure -- they were critical words. Some 
people have gone to a fair amount of effort 
to convince me that I was wrong. If things 
go well I'll hold the word eating ceremony 
next month. 



Now we're back at the root directory. The 
DIR command should show the files that were 
in the directory before you started this 
experiment plus the directories TESTD1, 
TESTD2. and TE5TD3. DIR TESTD1 will show 
an empty directory. Oik TESTD2 will show 
the directories TESTD21, TESTD22, and 
TESTD23. The following commands will all 
show the contents of the directory TESTD23: 
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STANDARD TERMINAL SUPPORT 
FOR OS- 9 



One of the first programs I wrote for a 
micro played "Life." The game starts with a 
given pattern, and. by repeatedly applying 
a set of rules, generates and displays new 
patterns. If the patterns are displayed 
properly on a CRT, the changing figures on 
the screen can be fascinating. (Note; Life 
was invented by John Norton Conway, and has 
been extensively discussed in Scientific 
American and BYTE.) I wanted my program to 
be usable with most terminals; so after 
investing a few days in the program, I 
spent another few weeks trying to make it 
"device independent." I never really fin- 
ished. It was an uncommonly fast game, 
but, since 1 couldn't generalize the termi- 
nal control, no-one without a H19 will ever 
be able to enjoy it. 

Many micros avoid this problem by not 
using a terminal (e.g., the Color Comput- 
er), but people, like me, who program com- 
puters without a built-in screen must 
either use only those control codes common 
to all terminals (like carriage return, and 
line feed), or expend a lot of effort writ- 
ing special code to handle different termi- 
nals. 

Full screen editors are the prime exam- 
ple of a type of program that must have 
control of some of the features of the ter- 
minal, but many other high quality programs 
support some of the features that most ter- 
minals share. Every program with general- 
ized terminal support must be configured 
for the terminal (or terminals) it is sup- 
posed to work with as part of the installa- 
tion of the program. 

Some programs use a special module 
which contains terminal -specif ic code for a 
few crucial functions. It is simple to 
install a program that uses this kind of 
terminal control provided that the neces- 
sary module is provided. If a suitable 
module for your terminal is not available, 
a new one must be written in assembly lan- 
guage . 

Another approach to generalized termi- 
nal control is to use a configuration pro- 
gram to ask questions about the terminal 
being used and store the information in 
tables which enable a single terminal con- 
trol module to drive any reasonable type of 
terminal . 

It is sad to see so much effort used 
solving the same problem over and over. It 
is so hard to write a program so it can be 
adjusted for use with any terminal that 
even some commercial programs don't do it, 
For small programs it can take more work to 
implement terminal support than to write 
the rest of the program. Frank Hogg Labs 
seems to have developed a standard for ter- 
minal control, the GOTOXY module. Once the 
module is installed for one program, it 
need not be done again except for a new 
type of terminal . If every software dis- 
tributor would standardize on GOTOXY . it 
would make life a lot easier for program- 
mers and purchasers of software. Frank 
Hogg tells me the GOTOXY modules are not 
proprietary, so this is an alternative -- 
UCSD Pascal makes do with no more. Unfor- 



tunately, GOTOXY is hard to call from some 
languages, and supports a terribly limited 
set of operations. 

I would like to propose a standard 
interface for CRT terminals. It would be 
much easier for Microware to build the 
standard control system than for me to do 
it, but it looks like the job is mine. I 
will kick the problems I find around for a 
month or so. Please help me with this. If 
I have to devise a standard in a vacuum, it 
may not please enough people to be widely 
used . 

Any standard is a compromise. The most 
important goal is to make it easy for any 
programmer to use the interface. This 
rules out all the language-specif ic inter- 
faces. The other two important goals are 
that all the currently existing programs 
with (or without) terminal control modules 
must continue to operate without modifica- 
tion, and that the interface should provide 
the most sophisticated terminal control 
possible. 

Since many languages can't use 
GETSTAT/SETSTAT, or otiper exotic ways of 
doing I/O, I believe the standard terminal 
control module should either be a callable 
module like GOTOXY, or some form of filter. 
The callable module would be more effi- 
cient; but different languages call subrou- 
tines differently, and it would be sad to 
forsake the built-in I/O facilities of a 
language in order to route all terminal I/O 
through a single module. There are several 
places a module could be placed in the ter- 
minal I/O path where it could act as a fil- 
ter isolating terminal specific control 
strings on the terminal side of the filter, 
and standard strings on the program side. 
I don't believe that the difference in 
efficiency between the filter and the sub- 
routine method of terminal control is all 
that great. The filter method seems to be 
the best approach to the terminal- 
independent program problem. 

The filter method requires that all 
programs act as if they are being used with 
some standard terminal. That terminal 
could be imaginary, but with so many dif- 
ferent terminals available why invent 
another. Two terminals seem like attrac- 
tive choices: the VT52 and the VT100. The 
VT100 is especially attractive because it 
implements the ANSI I standard. It would be 
nice to go with the accepted standard, and 
I think I will finally decide to use a sub- 
set of the AN5II standard -- a subset 
because I don't relish the idea of trying 
to emulate all those flashy features on a 
dumb CRT. The worst disadvantage of the 
ANSII standard protocol is that its cursor 
control sequences will be hard to generate 
in assembly language programs. The row and 
column have to be in ASCII characters. It 
hurts me to think of a programmer being 
forced to include binary-to-ASCII conver- 
sion code in his program just so the termi- 
nal control module can convert the numbers 
back to binary. The VT52 is representative 
of most moderately intelligent terminals. 
It certainly includes every function I 
would want to include in the subset of the 
ANSII standard I plan to implement. In the 
short run the VT52 is a better choice than 
the VT100; it could be emulated more effi- 
ciently, and would be just as useful as any 
practical subset of the ANSII standard. 
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?tin, I believe that in the long run 
-dhering to the most widely accepted stan- 
:iard is the best policy. I am looking for 
a good excuse to use the VT52 as the stan- 
dard, but haven't found a good enough one 
yet . 

The choice of the subset is another 
tricky decision. The minimum useful subset 
is either the direct cursor positioning 
command, or the set of cursor up, down, 
left, and right commands. Actually, home 
cursor is adequate for most purposes, but 
it takes a substantial amount of work to 
program for a terminal that is that dumb. 
There are many powerful commands that make 
it easier to program for a terminal, and. 
more important, cut down the number of 
characters that need to be sent to the ter- 
minal to accomplish some operation. If 
fewer characters need to be sent to (say) 
clear the screen, then the screen will 
clear faster and the number of interrupts 
the computer will need to service will be 
decreased. However, the more fancy termi- 
nal control commands are included in the 
standard, the larger the terminal control 
module will get . 

There Is no reason the filter trick 
can't be applied to terminal input as well 
as output. For some of the less powerful 
terminals it will be necessary to pass all 
input through the filter it order to know 
where the cursor is; however, all terminals 
will benefit from filtered input. An input 
filter will permit standard program func- 
tion keys, arrow keys, the clear screen 
key, and perhaps some other special keys to 



be def i ned . 

The following is a list of terminal 
control strings in descending order of 
likelihood to be in the subset: 

• Direct cursor positioning 

• Clear to end of line 

• PFkeys/Clear Key/Arrow Keys 

• Alternate cursor (block/ 
underscore)/normal cursor 

• Highlight on/off (either reverse video 
or intensify) 

• 25th (or other special) line support 
The following are significantly harder: 

• Save cursor position/return to saved 
posi t ion 

• Insert/delete line 

• Delete character 

• Enter/leave insert character mode 

I will consult everyone I can think of 
about this, and hope the people I don't 
think of will write or call me with their 
thoughts. After a month or two's thought, 
1 will try to write the cooe to support the 
standard for at least one terminal . I 
would appreciate any help or advice I can 
get . 
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One 5.25" floppy drive and contrc'ier 
-- $600.00 



Last month I promised that I would eat 
some words this month. In the first column 
I wrote for 68 Micro Journal , I said that I 
was sorry no one was using more than 64K 
for a single program under OS-9, and I made 
the point rather strongly that 6S09-based 
computers should not be shared. 

Several months ago David Brown asked me 
to look at his version of MUMPS for the 
6809. Strictly speaking, since MUMPS 
doesn't run under OS-9, it is out of my 
area, but it is intriguing. The version of 
MUMPS David Brown sent me uses a fairly 
sophisticated virtual memory scheme, and is 
not effected oy 64K boundaries. Since it 
doesn't run under OS-9, I still challenge 
someone to be the first with a program that 
uses more than 64K at once under OS-9, but 
since Dave Brown's work is impressive, I 
gave it a mixed but generally nice review. 

My mother is the secretary of the 
school board back in the town where I grew 
up. She has given me a very interesting 
pipel ine into the workings of a municipal 
school system. Recently there has been a 
lot of fuss about computers at school . 
Pre-college schools have to make a number 
of difficult decisions in the process of 
integrating computers in the educational 
process. Even the choice of the best com- 
puter is complicated for them by the scar- 
city of good software for their purposes 
(and their uncertainty concerning what 
software they need), and by the worst kind 
of financial problems. When I heard that 
my home town was going to commit itself to 
a gaggle of microcomputers running Basic. I 
felt motivated to research the subject with 
an eye toward talking them out of Basic. 
The OS-9 users' group's bulletin board is 
often a good source of information, and in 
this case it was surprisingly useful; it 
turns out that many OS-9 users are involved 
in education. Once started on the idea 
that 05-9 might be a good solution for some 
of a schools system's problems, I rubbed 
some figures together and came to some con- 
clusions that shouldn't have surprised me. 

It is clear that financial considera- 
tions are crucially important to all the 
school systems I know of. One micro can be 
inexpensive enough to fit into a budget, 
but one Apple is not very useful for teach- 
ing a class of thirty. I figure that a 
high school computer lab should be set up 
to teach Pascal, word processing, the use 
of a spread sheet, and the use of computers 
in the sciences. I know from experience 
that students can be lab partners and work 
as a team of two without too much trouble. 
but three or more students working together 
will have problems. Figuring thirty stu- 
dents in a class, the lab will need fifteen 
stations. The minimum configuration I can 
put together is fifteen micros, each 
including: 

• A spread sheet — $100.00 

• Pascal -- $200.00 

• Wordstar type editor -- $300.00 

• Operating system -- $100.00 



A printer -- $250.00 
A monitor -- $200.00 



The micro 



$500.00 



All those prices are rough, but reflect the 
cheap alternative, not the quality that 
students deserve. Each micro will come to 
$2250.00 (though I doubt that they could 
actually be put together for that little). 
Fifteen of them cost $33750.00. That's 
serious money, and it only buys a minimal 
system for each lab team. 

If a large DS--9 system could handle 
fifteen students, it would be possible to 
purchase a top of the line CPU with a hard 
disk, a floppy disk. , f if teen serial ports 
(intelligent), a half meg of memory, and 
top of the line software, for about 
$14,000.00. Fifteen very nice terminals 
would cost $9000.00 bringing the cost of 
the system to $23,000.00. Two thousand dol- 
lars will buy a very nice printer, bringing 
the total cost to about $25,000. 

I have talked to several people who run 
many users on a Gimix-III system. If half 
of what the Gimix-III users say is true, it 
would be reasonable to have eight or ten 
students sharing a machine. If all that 
they say is true, it might be possible to 
hook thirty students to one CPU and expect 
them to run at a reasonable speed. I now 
have a second terminal on my level two sys- 
tem. I can say from my own experience that 
my system can handle two users with very 
few signs of being loaded down. 

Based on what I know about my system, 
and what I have been able to find out about 
Gimix-III, I think a Gimix-III system with 
at least 256K of memory would be able to 
handle four to six users with a level of 
service that I would find acceptable. Giv- 
en a choice of a toy computer with bargain 
basement software, and the bare minimum of 
peripherals, or a fifteenth of a fully con- 
figured Gimix-III system; I would pick the 
piece of a large system like a flash. 

I confess to being an ivory tower 
idealist. I want people to like computers, 
so I flinch at the idea of giving out slic- 
es of computer so small that there is not 
enough power to allow software to be 
friendly. That means that I think a indi- 
vidual deserves at least a level two system 
with lots of memory. Realistically, most 
hobbyists can't afford to commit that much 
money to their computer; businesses need a 
much stronger argument than friendly rela- 
tionships between staff and computers; and 
schools simply have to choose the least 
expensive way to do things most of the 
time. I maintain that I am philosophically 
opposed to sharing micros, but if I am 
forced to consider the alternatives, I am 
strongly in favor of sharing a computer -- 
provided it is the right computer. 
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A LETTER The assembler program which was includ- 

ed with the letter, and which I will 
Don Williams sent me a letter from Bengt- include here, is an interesting extension 
Allan Bergvall who sent along an interest- on the program called "StrtTask" which I 
ing program that amounts to a special sort gave a few months ago. If we were using 
of shell for BasicOS programs. It gives me real UNIX we would solve the problem of 
encouragement 1n my plan to write a passing parameters to BASICOS programs by 
enhanced shell, but is useful as it stands. modifying the shell; ParamMod is a sort of 
His letter follows this column. special purpose mini-shell which runs 

BASIC09 programs. 

LETTER FROM BENGT-ALLAN BERGVALL 

Microware's BASIC09 is an excellent interpreter, easy to use for producing your 
ovm utilities. Unfortunately, it is lacking a straightforward method of passing 
parameters. For example, if you are going to write a "Help" utility, you want to 
type 

0S9:help dir 

to learn about the dir command. This, is impossible if Help is a BASIC09 program. 
If Help is a packed BASIC09 program, interpreted by RunB , you can type 

0S9:help 

only, and let the program ask you what help you want. If you don't have RunB, 
you have to type 

OS9:basic09 #5k help 

However, even if Microware doesn't tell you, you can also pass parameters in RunB 
or BASIC09 by using the syntax 

0S9:help ("dir") or 0S9:basic09 #5k help ("dir") 

and using the PARAM statement in the Help^ program. This is OK if you will use 
the program rarely, but if the program will be used often, and perhaps not by 
yourself, this is a very clumsy syntax. 

The desired syntax can of course be accomplished by writing Help in another 
language that permits the desired parameter syntax, i.e. in assembler. This is 
probably the wront way for a user utility program. To solve the problem, I have 
written a short "universal" program in assembler, called ParamMod, with the fol- 
lowing characteristics: 

• ParamMod allows the desired parameter syntax. 

• ParamMod transforms the parameter list from the desired syntax to the syntax 
required by BASIC09 or RunB. The resulting parameters are all of the type 
STRING. To be used as numeric types, the strings have to be transformed 
using the VAL function. 

• ParamMod forks to either BASIC09 or RunB, and the main program is written in 
BASIC09. 

• ParamMod has to duplicated and customized on three text strings and needed 
BASIC09 memory for each utility: 

- innam 

The wanted utility name. In the given case, Help. Other utilities could 
be names Compare or Analyze. 

- Outname 

The name of the file that contains the BASIC09 procedure and performs 
the desired action. It could be named Help_B or /DO/COM/Compare_B or 
AnalyzeBody.interprt. 

- interprt 

The name of the BASIC09 interpreter to be forked to. Either BASIC09 if 
outname is a saved procedure or RunB if it is a packed procedure. 

- Memory 

The total number of bytes needed for the procedures and their data are- 
as. 
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In the following, we are assuming you are writing a Help utility. For other 
utilities, change the names accordingly. 

First customize ParamMod's three text strings and BASIC09 estimated memory 
size with your text editor. Then assemble it with Microware's assembler, using 
the command: 

0S9:asm ParamMod o=Help #10k 

and the resulting code for Help will be in your execution directory. 

Then write your BASIC09 program, naming the outermost procedure Help B. You 
must save or pack Help_B to run it through Help. RUN it from within BASICt)9 with 
the command (including parameter) : 

B:$help dir 

You may also durinc the development phase run the program without Help. In that 
case you must use BASIC09 parameter syntax: 

B:run help_b("dir") 

Included is the assembly listing for ParamMod, customized for a Help utility and 
a dummy Help_B program. 

Bengt_Allan Bergvall 

Blavingev, 1 

S-561 59 Huskvarna 

Sweden 
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PARAMMOD 

')^ Program written by Bengt-Allan Bergvall, Blavingev. 1, 
7 s-5ol 49 Huskvarna, Sweden. 

'; Program to reformat a parameter list from an easily 

7 typed form to the clumsier form required when runnint a 

'I BASIC09 program, ^ 

7 Given the command 

'I 0S9:help paraml param2 paramA (note the extra space) 

'^ This program will fork to the RunB or BASIC09 program 

7 Help B as if given the equivalent command: 

^^ 0S9:"BASIC09 #5k Help^Brparaml", "param2", "", "param4") 

it 

■^ This program is general and can reformat the resulting 
; parameter list up to 256 characters, but the name 
7 strings inname and outname has to be changed for each 
^' implementation. 

'; if interprt is runB, then outname has to be a packed 
]^ BASIC09 program in the execution directory. 

" If interprt is BASIC09 then outname has to be a saved 
7 BASIC09 program either in the present data directory or 
;^ in another file with outname giving the full path name, 
- e.g., /D0/COM/Help_B - ^ 

^ The memory needed by BASIC09 or RunB must also be 

* given. 

nam parameter list modifier 

ttl for BASIC09 or RunB 

ifpl 

use /DO/DEFS/defslist 

endc (use os9defs) 

mod pgend, inname,prgrm+objct ,reent-»-l 

fdb pgstart, stack 
'^ data variables 

parendS rmb 2 output parameter limit -5 
outpar rmb 256 
varend equ . 
stck rmb 200 stack area 
staci* ecu . stack pointer 

"* Customization area 

inname fcs .Help. Name of utility 

outname fcs .Help B, Name of BASIC09 procedure 

fcb 
interprt fcs .BASIC09. Either BASIC09 or runB 
« Total memory needed in bytes by BASIC09 or RunB 
'^ process: (equivalent to the needed BASIC09 MEM value) 
memory equ 5000 

'"'' End customization 

pgstart 

'^ Modify parameter list from free form into BASIC09 
^ strinz form, Exanple of free form: paraml param2 param4 
Resulting BASIC09 string form: 

* Help_B (^paraml", "param2","","paramA") 

2 prepare limit check for parameter list, allow for 
ending last parenthesis, 
leay varend-5,U 
sty parendS 

* copy outname into output parameter list 

?shs X 
eay outpar, U 
leax outname, PCR 
namechar Ida ,X+ 
beq nameend 
sta ,Y+ 
bra namechar 
nameend puis X input parameter list 

* append modified input parameter list to output 
"^ parameter list 

Ida #'( 
sta ,Y+ 
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Ida #•" 

sta ,Y+ 
parchar Ida ,X+ 
*^ check the resulting parameter list not too long 

cmpy parendS 

bio parOK 

comb set carry 

Idb il56 BASIC09 parameter error 

0S9 F$Exit 

parOK cmpa #$20 space? 

beq nexipar 

cmpa #$0D carriage return ends parameter list 

beq lastpar 

sta ,Y+ 

bra parchar 
* reformat next parameter 
nextpar Ida #'" 

sta ,y+ 

Ida //', 

sta ,y+ 

Ida ^/*" 

sta ,Y+ 

bra parchar 
'^ list. end 
lastpar Ida #'" 

sta ,Y+ 

Ida jr) 

sta .Y-*- 

Ida #$0D carriage return 

sta ,Y+ 

" fork to interprt (RUnB or BASIC09) 

leax interprt, PCR 

Idy #S100 allow one page parameters 

leau outpar,U 

Ida #prgrm+objct 

Idb #1:memory+255)/256 data area 

0S9 F$Fork 

bcs ut 

0S9 F$Wait 

bcs ut 

clrb no error 
ut 0S9 F$Exit 

emod 
pgend equ * 

end 



HELPB 

PROCEDURE Help_B 

REM Dummy Help utility 

REM prints the parameter 

PARAM text: STRING 

PRINT text 

BYE \REM bye needed to give automatic return to OS-9 when run by Basic09 



Column Seven 45 



^ OS-9 User Notes Volume I 



COLUMN EIGHT 



THE OS- 9 USER SEMINAR 

On August 12 the OS-9 User Seminar opened 
rather slowly as I and a few other people 
stood in Tine in front of the exhibit hall 
on the third floor of the Des Moines Mai — 
riott. We watched as various Microware 
staff struggled to get a Radio Shack com- 
puter (running DS-9 of course) interfaced 
with a television. When I got into the 
halU I was surprised at the number of 
exhibitors. I have always thought of the 
OS'S community as about the size of a large 
family -- there were 24 booths listed in 
the exhibitor guide. I had a ball wander- 
ing through the hall, meeting people 1 have 
only known through phone conversat ions» and 
seeing some exciting hardware. 

Several of the exhibitors were showing 
machines that used OS-9 as a process con- 
trol environment. One booth sported a rack 
of equipment that would have been more at 
home next to an assembly line. 

Smoke Signal broadcasting had a video 
tape rig showing a movie of a military- 
looking man. I remember a bugle^nd a lot 
of strutting up and down, but I just can't 
remember what he was talking about; I think 
he was promoting the TMP package. Smoke 
Signal had a compact SS50 based machine 
that I have never seen before. 

There were a couple of Japanese engi- 
neers demonstrating Fujitsu FM-7 and FM-11 
computers. Very well done. I wish they 
were available in this country. A particu- 
larly nice feature of the software on the 
Fujitsu machines was split-screen support. 
I saw them editing on one part of the 
screen while two other sections displayed 
moving graphics ... all running at the same 
time . 

Tano was showing a Dragon computer, 
imported (I believe) from England. The 
Dragon is a small. inexpensive computer 
with color graphics and OS-9 Level One. I 
only saw it playing games, but it does that 
pretty wel 1 . 

Privac was showing the graphics board 
that I have been coveting for months now. 
It looks even better in reality than it 
appears in an advertisement. There was a 
program running almost continuously that 
demonstrated the board. Figures and char- 
acters would appear, disappear, rotate, and 
float across the screen. I had always won- 
dered how well the Privac board was sup- 
ported under OS-9; it turns out that OS-9 
is the operating system they use. The demo 
program was written in Basic09. 

Wires from the Gimix booth seemed to 
spread all over the hall. The 05-9 User 
Group, JBM Group, and Frank Hogg Labs all 
were borrowing computer services from 
Gimix. Perhaps to demonstrate the tireless 
ability of GMX-III to spew characters out 
on many terminals, unused terminals were 
kept busy listing strange programs. When- 
ever I walked by, one of the terminals at 
the FHL booth was listing a COBOL program. 
At the Gimix booth I met the engineer 
responsible for my hardware (who is also 



the president and the service manager of 
Gimix). He thinks Gimix hardware should 
move in about the same direction I want it 
to go. If things go well, there should be 
some terrific new hardware coming out some- 
time in the indefinite future. 

The JBM Group is hard for me to charac- 
terize. They had some utilities that 
sounded good except that they were written 
at least partly in Basic09. The thing that 
upset and fascinated me was that they have 
a sort which they claim runs very fast. 
They claim to have compared their sort to a 
standard disk-based merge sort, and come 
out significantly better. Either the algor- 
ithm used by the program they compared 
theirs to was not the best available in the 
literature, or their claim may have to be 
placed in the same class as perpetual 
motion machines. The man who invented 
their sorting algorithm wasn't there for me 
to ask about the detalTs of his method, and 
I had no way to check their figures, so I 
will continue to view their sort with skep- 
ticism; however, even if it is only an 
average sort, its manual documents a fine 
general sorting program of a type which is 
much needed by serious OS-9 users. They had 
several other packages including a set of 
Basic09 subroutines for ISAM file handling 
that sounded much less exotic, but inter- 
esting. 

There were, of course, many exhibitors 
I haven't mentioned (for example Micro- 
ware's own booth), but I don't intend to 
make this column into a walking tour of the 
exhibit hal 1 . 

Friday there was plenty of time to look 
around . Saturday and Sunday were so busy 
there was barely time to eat. Microware 
filled most of the weekend with classes, 
presentations, and "round tables" ranging 
from OS-9 and BasicOS Features, which cov- 
ered things like the Basic09 editor, to the 
OS-9 Roundtable, which gave us a chance to 
interrogate the parents of OS-9 about its 
workings. In the evenings a few of the 
exhibitors ran "hospitality suites" which 
gave some of us an excuse to stay up late 
and talk about our computers. 

Saturday night there was a meeting of 
the OS-9 User Group. The User Group Is 
having some troubles which seem to stem 
mostly from having only a few members 
spread over a wide geographical area. We 
elected officers for the next year: Dale 
Puckett (President), myself (Vice Presi- 
dent), Goerge Dorner (Treasurer), and Tom 
Murphy (Secretary). We are respectively 
responsible for the Software Exchange Com- 
mittee, the Membership Committee, the Com- 
munications Committee, and the By Laws Com- 
mittee. 

Monday those of us who were still left 
around went off to Microware' s offices. I 
had a chance to discuss some of the diffi- 
culties I am having with 05-9 and C with 
the appropriate people, and discovered that 
those programmers are seriously crowded. 
They desperately need to make the move to a 
larger facility that they have been plan- 
ning. 
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SHELL COMMANDS 

•he shell is a program that interprets com- 
and lines and does what is called for. 
"ne full UNIX shell is a programming lan- 
guage in itself. The OS-9 shell is only a 
"subset of the UNIX shell, but it has enough 
flexibility to be useful. The first thing 
to learn about the shell is how to use the 
built-in shell commands. The chd» chx. ex, 
kill, w, and setpr commands are built into 
the shell. The shell commands are used to 
control the environment of the programs 
tnat are run by the she! 1 . 

I use the chd command, which is the 
command which changes the working data 
directory, more than any other shell com- 
mand. The working data directory is the 
directory which will be used for most files 
you read or write without specifying a 
directory in the file name. It is usually 
much better to change the working directory 
than to explicitly include directories in 
file names so I frequently change directo- 
ries as I change from one task to another. 
It is a rare day when I use the chx com- 
mand, the command which changes the working 
execution directory, even once. I imagine 
that someone with a smaller system disk 
than mine would use the chx command much 
more frequently than I do because OS-9 
remembers where the working directories are 
on disk, and needs to be reset with chd and 
chx commands when a cisk is changed. If 
you forget to change directories when you 
change disks, OS-9 will give you a nasty 
message next time you try to use the direc- 
tory. I have ne\/er gotten into trouble by 
forgetting, but It is not wise to trust an 
operating system too far. 

The ex command should be classed as an 
advanced command. It replaces the shell 
with another program. Replacing the shell 
is certainly a good thing to be able to do, 
especially for users with smaller systems, 
but it can have disconcerting results -- 
mainly that when the program ends. the 
shell won't be there. 

The rest of the shell commands are pri- 
marily useful for those who run programs 
concurrently. You can instruct the shell 
to start a program running, then give you 
another shell prompt by putting an & after 
the command on the command line; 

0S9: dir >/p& 

would list the files in the data directory 
on the printer while you run other pro- 
grams . 

If you run programs concurrently, the 
kill, setpr, and w commands will be useful. 
The kill command should be used about the 
way you use the quit control key (usually 
<CNTL>0 or <CNTL>E). The quit key only 
works on tne last program to do I/O to the 
terminal, the kill command works on any 
program. The setpr command is used to con- 
trol the way the computer's resources are 
divided up. The higner the priority of a 
program, the larger a share of the computer 
it will get, and the faster it will run. A 
program's (or, more properly, process's) 
priority can be anywhere in the range 1 to 
255. The w command causes the shell to 
wait for a child process to finish. That 
means that the shell won't prompt for 
another command until a program that was 



started by it terminates. The main use of 
this command is to recover from the mistake 
of running a program that does I/O to the 
terminal in background. The usefulness of 
the w command can be appreciated by trying 
the following experiment: 

0S9: dir x& 

Now try to get some useful work done . . . 
when you are disgusted with the screwy 
behavior of your terminal, type w at the 
059 prompt : 

0S9: w 

There is one particularly nice feature 
of the shell which is, so far as I know, 
undocumented. If you run a program like 
the assembler with its output directed 
somewhere other than the terminal , then 
decide that you would like to run another 
program at the same time, you can cut the 
assembly loose from the shell with the 
interrupt control key (usually <CNTL>C). 
The interrupt control key will usually ter- 
minate the program which most recently did 
I/O to the terminal, but, if the p'^ogram in 
control of the terminal (the assemblef^ in 
this case) doesn't do any I/O to the termi- 
nal at all, it won't kill it. Instead, the 
shell sees the interrupt, and converts the 
program in control of the terminal to a 
concurrent program. 



A LOGICAL DEVICE DRIVER 

This column is an experiment with a new 
format. There is a demand for information 
for new OS-9 users, but I have also heard 
requests for more advanced discussions. In 
this column I am tryino to include some- 
thing for everyone. What follows may be of 
general interest, but, for an inexperienced 
computer user, it may be heavy going. 

Several months back I started a project 
whose objective was to find a way to give 
OS-9 a terminal -independent way to control 
CRTs. I have a special device driver which 
does just what is called for, but it is 
built around Microware's ACIA source. I 
may be able to get permission from Micro- 
ware to publish the modified driver, but I 
would rather not have the terminal mapping 
tied that closely to the computer's I/O 
port. Not every computer uses an ACIA chip 
for its serial interface, and my special 
driver only works with ACIA serial inter- 
face chips. What is needed is a virtual. 
or logical , device that can insulate the 
terminal mapping code from the physical 
interface. 

The idea of a logical device driver has 
many applications beyond a terminal- 
independent interface. At the User Seminar 
I spent some time talking to the engineers 
from the Fujitsu booth. They wanted my 
opinion • of a proposal to make logical 
devices a part of OS-9 in order to allow 
the system drive to have a consistent name 
regardless of the type of hardware being 
used. This would make It easier to write 
programs that referenced files on the sys- 
tem drive. A logical device can certainly 
do this. It would be possible to set up a 
logical disk with some obvious name like 
SVS, and have it know the name of the phys- 
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ical drive being used as tne system drive: 
DO, HO, or whatever. 

The laea can be extended even further. 
There is no compelling reason why the log- 
ical device should refer to exactly one 
physical drive. The logical device could 
refer to several physical devices or just a 
part of one. 

Some possible uses of the concept are: 

• A disk drive with associated cache 
storage . 

• A neat, and fairly easy way to support 
split screen terminal displays with 
each section of the screen treated as 
a separate terminal . 

• A gateway to a network. 

• A way to associate a printer with a 
terminal for screen dumps. 

• A. terminal - independent interface. 

The device driver I have included with 
the column is a logical SCF device driver 
for a Level Two system. A RBF driver, or a 
driver for Level One would be somewhat dif- 
ferent, but only the details would need to 
be changed. The driver. which I named 
VCIA, doesn't do anything at all except 
waste time. It is a skeleton for something 
interesting to be built on. 

Starting from the top, let's go through 
the interesting parts of the program. A 
logical driver must look just like a real 
driver to the system, so it must have the 
type Drivr+Objct, and it must have a byte 
after the normal module header reflecting 
the modes in which the driver can be used. 
This one says it is good for update, it 
might be a good idea to add execution. The 
storage required by a device driver is 
called the device static storage, it is 
allocated, and partly initialized by the 
file manager, in this case SCF. The file 
manager uses the first section of the 
device static storage, the storage reserved 
for it with the "org V.SCF." 

Performance is crucial at this level. 
Every character read from or written to the 
terminal will pass through this module so 
even a small improvement in efficiency is 
good. Normal good coding practice is still 
important, but the priorities shift some- 
what. SCF will branch to entry, entry+3, 
entry+6 ... depending on what service it 
wants. The normal convention is to put a 
list of Ibra Instructions here, but a bra 
instruction is a little faster, so I used 
them and padded them to three bytes each 
with nops (which are never executed in this 
context ) . 

The INIT call must find the physical 
device driver and set up the proper envi- 
ronment for it. The physical driver, which 
I call P.D., is found and mapped into the 
address soace with a F$LINK call. This is 
a bit tricky. In Level Two, the module is 
linked into the address space belonging to 
the process doing the link. The device 
driver uses the process number of the pro- 
cess that opened it, but it runs in the 
system address space. I had to fool the 
operating system into thinking I was run^ 



ning under the system process number by 
playing with the pointers in the system 
direct page. If this were Level One, I 
think I could have simply used a F$SLink 
call without all the fussing around. 

The real device driver is going to need 
its own device static storage, so the log- 
ical device driver plays SCF for a moment 
and gets the amount of storage P.D. needs. 
I use the Level Two system memory request, 
Level One users can probably use the Level 
One analog. The address of the memory must 
be saved for future calls, and I save the 
size for convenience,, 

One never knows when SCF will change 

its part of the static storage, so before 

each call information from VCIA's static 

storage must be copied to P.D.'s static 
storage, and after each call information 

must be copied back from P.D.'s static 
storage, to VCIA's. 

The INIT call, and each other call, 
basically changes from VCIA's static stor- 
age to P.D. 's- and calls the appropriate 
entry in P.D. 

The TERM entry is responsible for 
cleaning up as the device is closed. After 
calling P.D. to allow it to close down the 
physical device, it frees the device static 
memory that IMT allocated for P.O., and 
unlinks P.D. It is worth noting that TERM 
is the mirror image of INIT. 

The device descriptor I use for VCIA is 
called VTERM. Since SCF thinks VTERM is a 
real device, its device descriptor is 
important. Even the address of the port 
that VTERM uses is important. If you keep 
things as simple as I did, the logical 
device driver will map everything including 
the Information from the device descriptor 
directly to the physical device driver, 
but, if you want to support something like 
split screen, you will have to give each 
logical terminal a different port address, 
or SCF will know they all are referring to 
the same device, and get in the way. 

Fortunately this virtual driver works 
with GIMIX I/O processors. This is pure 
luck because GIMIX doesn't publish enough 
Information about their driver for me to 
design an interface for it. Let's consider 
this a gentle push for Richard Don at Gimix 
to release more Information about his pro- 
prietary software. 

It should be possible to move a good 
deal less data back and forth between 
VCIA's and P.D.'s static storage than I do, 
but I played it safe in spite of the large 
cost. It would be good to try to find some 
fields that don't need moving so time could 
be saved by not moving them. 

This module demonstrates that, although 
OS-9 Level One is compatible with Level Two 
for user programs, it is not compatible for 
system modules. This shouldn't be a sur- 
prise, but It is something to be cautious 
atout . In many cases all that needs to be 
changed is an entry in a definitions file, 
but if you try to run VCIA as it stands 1n 
a Level One system, the best you can hope 
for is that it will give an error code and 
quit . 
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Debugging code in system state is no^ 
something I will do if I have a choice. 
The debugger won't work on modules that 
need to run in system state, and debugging 
code that writes out helpful messages as a 
program runs doesn't make sense in a device 
driver module. If the driver doesn't work 
wnat do you write to? I debugged this mod- 
ule by using its return code. If you have 
VCIA set carry before it returns to SCF, 
the program that is trying to use it will 
get the value that was in the B accumulator 
when VCIA returned to SCF. This a slow way 
to learn things, but it works. 

One final point: it is expensive, but 
otherwise impeccable technique to pile log- 
ical device on logical device. VCIA has no 
way of knowing whether the device it 
oelieves controls the physical device is 
real or logical . 



Microware is said to have an "Over the 
top" debugger that can be used to debug 
system software. The only person I know 
ttimt has looked into it says it doesn't 
woT*c^^ with version 1.2 of OS-9. It seems 
MiCTOware now uses debugging hardware. 
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VCIA DEVICE DRIVER 



Vc 

-k 

-k 
k 

iftr 

yc 
lit 
VV 

Vc 
^- 



nam vcia 

ttl Virtual (logical) device driver 



This module should be used as a SCF (Sequential 
Character File) device driver. It doesn't 
drive any specific device, but, rather, calls 
a physical device driver, such as ACIA, to 
deal with the physical device. 
Possible uses: 

Mapping various terminals to a standard 

Implementing windows. 

Linking a PlA and an ACIA to provide 

switchable printing of terminal output 



k 
k 



As it stands this m9dule is a dummy. It passes 
all calls through with minimum interference. 

The INIT call must set up the environment for 
the device driver before passing the call on. 

Read, write, getstat, and setstat can probably 
get away with less than they do, but all 
variables are mapped between control blocks 
to ensure that this module is transparent. 

The TERM call must release memory allocated for 
the physical driver before returning. 



-k 
•k 

k 
k 
k 
k 
k 
k 
k 

k 
k 
k 
k 
-k 
k 
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k 
k 
-k 



IFPl use /DO/DEFS/defslist 

use /HO/DEFS/defslist 

ENDC 
Type set Drivr+Objct 
Revs set ReEnt+1 

MOD VciaLen, Name, Type, Revs , Entry, MemSize 

fcb Updat. Driver can be used for updated (read + write) 
Name fcs /VCIA/ 

fcb 1 edition number 
PDNam fcs /ACIA/ 

•kkkkk-k-kkkitie 

* Device static storage for this virtual driver 

k 

org V.SCF room for SCF variables 

PDModH rmb 2 Pointer to Physical Driver's Header 

PDModE rmb 2 Pointer to Physical Driver's Entry 

PDModM rmb 2 Pointer to Physical Driver's Static Memory 

PDModMS rmb 2 amount of memory allocated for PD static mem 
MemSize equ * 

spc 2 

kkkitiz'kkkkititkk 

'^ Block of entry points 

Entry 
bra Init 

nop pad out each entry to three bytes 
bra Read 
nop 

bra Write 
nop 

bra Getstat 
nop 

bra PutStat 
nop 
Ibra Term 

ific^kkifkkk'kitk'k'k 

k 

k 

k 

k 

k 



Init finds the driver it will use a physical device driver, 
and allocates and initiallizes its static storage 
Passed: 

U Points to static storage 

Y Points to device descriptor 



Init 
pshs Y,U 

ickk-kkkk-kk 

* adjust process number to system process 



II 



* so' the 

Idd D.Proc 
pshs D save A 



nk will be into the system address space. 
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^^ At this point X points at vcia's static storage 
'• U points to P.D.^s stati< 



Idd D.SysPrc 
std D.Proc 

Ida #Type driver module type 

leax PDNam,PCR point X at the name of the P Driver 

0S9 F$Link 

puis D restore old process number 

std D.Proc 

Ibcs Errorl 

Idx 2,S copy address of device static store to x 
stu PDModH,X save P.D. 's Module Header address 
sty PDModEjX save P.D.^s Entry address 

Idd MSMem,U memory requirement of P Driver 

0S9 F$SRqMem request system Memory 

ibcs Errorl 

std PDModMS,X save amount of memory allocated 

stu PDModM,X save pointer to memory 

: this p 
points to P.D.^s static storage 

Idb #V.SCF length to move 

* Move the entire set part of the device static storage 
'■^ into P.D.'s static store. 

Vc 

LMoveE 

decb 

bmi XMove 

Ida B,X 

sta B,U 

bra LMoveE go around loop again 
XMove 

puis y but leave U in the stack 

yc :^yir ^ ?V ir :if Vc * ^V :V ?VVr Vf A 

7 U points to P.D.'s static storage 
" Y points to the device descriptor 

Idx PDModE,X 

jsr D$Init,X do P D init 

tfr U,X 
puis U 
pshs B 

'* now X points at PD static store 

* U points at vcia static store 

bsr Mapin 

puis B,PC return to SCF 

spc 2 

^-5 * 

''' SCF needs to see any changes the physical device * 

* driver makes to V.Paus, (or V.Err). * 

* X points at P.D. static storage. * 

* V points at vcia static storage. * 

* - i^ 

Map In 

Idb V.Paus, X 

stb V.Paus, U 

Idb V.Err,X 

stb V.Err,U 

rts 

spc 2 
Read 

Idb #DSRead 

bra Coamon 

spc 2 
GetStat 

Idb #D$GSta 

bra Connon 

spc 2 
PutStat 

Idb #D$PSta 

bra CoBtmon 

spc 2 
Write 

52 OS-9 User Notes Volume I 



Idb #D$Writ 
spc 2 

* Code used by all entries except INIT ']" 

^ Passed B — offset from P.D's entry point for this op.^'^ 

Common 

pshs D,U 
Idx PDModM,U 

?'c . ^f 

^^ The physical device driver needs to have '"^ 

V.LPRC, and V.BUSY copied to it each time it is * 

') called. '; 

^'^ At this point U points at vcia static storage, '' 

'^^ X points at P,D static storage. ^^ 

-k 1 r ^v 

Idd V.LPRC, U 

std V.LPRC, X 

Idd V.LPRC+2,U 

std V.LPRC+2,X 

Idd V.LPRC+A,U Line 

std V.LPRC+4,X 

Idd V.LPRC+6,U Dev2 

std V.LPRC+6,X 

Idd V.LPRC+8,U Intr 

std V.LPRC+8^X 

Idd V.LPRC+10,U PChr 

std V.LPRC+10,X 

Idd V.LPRC+12,U XOn 

std V.LPRC+12,X 

spc 2 

'^ The P.D. requires Y, and A to be as they were *; 

* when vcia was called. A and Y haven't been '*' 

* been disturbed. ^ 
'*l U must point to P.D.'s static storage. ''' 

* When Common was called, * 
'^ B pointed to the offset from P.D.'s entry point * 
''^ that we should jump to. * 

Idx PDModE,U 

Idu PDModM.U 

puis D recover offset in P.D. and A from stack 

jsr B,X 

spc 2 

tfr U,X point X at PD static storage 

puis U recover pointer to vcia static 

Eshs B save return code 
sr Mapin (X points to PD static, U points to vcia static) 
puis B,PC return to SCF 
spc 2 
spc 2 
Term 
Idb #D$Term 
bsr Common cal 1 PD 
pshs CC,B,U CC and error # from P.D. 

tfr U,X 

Idu PDModM,X address of PD static storage 

Idd PDModHS,X size of memory 

0S9 F$SRtMem return memory 

bcs Error2 

Idu PDModH,X address of module header 

^ adjust process descriptor to system process 

ii 

Idd D.Proc 

fshs D save D 
dd D.SysPrc 
std D.Proc 
spc 1 

0S9 F$UnLink unlink PD 
puis D recover old process descriptor 
std D.Proc and restore it in place 
bcs Error2 
spc 1 

puis CC,B,U,PC return to SCF 
spc 2 
Errorl 
puis Y,U 
rts 
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Error2 

leas 2,S clear CC and B off stack 

puis U,PC return to SCF 

spc 2 

EMOD 
VciaLen equ * 

use vterm 

END 



54. QS-9 User Notes Volume I 



COLUMN NINE 



PROTECTION 

As I was working away, distracted by the 
problem of choosing a topic for this 
month's column, I deleted a bunch of files 
by mistake. Worse, I didn't notice that I 
had done myself in until minutes later -- 
too late to get the files back. This event 
made the choice of a subject for this month 
substantially easier. The first topic for 
this month Is file security. 

Users on OS-9 are known by a number . 
If you use OS-9 as it came off the distri- 
bution disk you will be the only user and 



have the user number 0. User is special : 
UNIX users would call him the superuser. 
The superuser has special privileges that 
enable him to circumvent the protection of 
files. All other users, and, to some 
extent the superuser, are separated from 
disk files by OS-9's file protection 
scheme . 

If you use the DIR command with the "E" 
opt ion : 

0S9: DIR E 

you will get a list of the files in your 
current working directory with a lot of 
information about each file as illustrated 
in Figure 2. 



directory of , 19:50:32 
Ovmer Last modified attributes 


sector byt 


e count name 


1 83/05/10 2234 wr 

1 83/09/11 2351 -s— r-wr 
1 83/06/11 1630 r 

83/09/14 2036 d-ewrewr 

1 83/08/28 1614 r-wr 

Figure 2: Output of DIR Command 
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The information in this display that 
relates to a file's protection are its own- 
er and attributes. All the files in this 
directory, except , the file (a directory 
file) called PROGRi^^MS, belong to user num- 
ber 1. The type of protection given to a 
file depends on the contents of the attri- 
butes field. 

The first position in the attributes 
field is for the directory attribute. 
Directory files have several special char- 
acteristics, the one relating to protection 
is that they can't be deleted with the DEL 
command . 

The second position in the attribute 
field is the shareable attribute. If there 
is an "s" in this position, the file can 
only be accessed by one process at a time. 

The next six positions in the attribute 
field are two groups of three attributes 
each; public execute, write and read, and 
private execute write and read. If a pub- 
lic attribute Is on (indicated by a letter 
instead of dash in that position) then any 
user can do that class of operations. If a 
private attribute is on, the owner of the 
file can do that class of operation. 

The file called Column4 has typical 
protection. User 1, who is the owner of 
the file, can read or write it, and nobody 
else can do anything to it except observe 

that it is there. 

Columns is protected such that any user 
can read the file, but only user 1 can- 
write to it. It also has the non-shareable 
attribute which protects it against being 
accessed by more than one user at a time. 
The non-shareable attribute prevents things, 
from getting confusing when user 1 is- 
updating the file and some other user is? 
reading it, by preventing that situation^ 



from coming about. Whoever gets to the 
file first has exclusive access to it until 
he closes it. If several users want to 
read a file at the same time there is usu- 
ally no reason not to let them do so, prob- 
lems start to appear when a user wants to 
write to the file while other access it, 
and things get really sticky if several 
users want to update the file at the same 
time. The non-shareable attribute Is most 
important when several users want write to 
a file concurrently. 

The protection of columns demonstrates 
one of the more useful applications of file 
protection in a single user system. It is 
impossible for anyone, even the owner of 
the file, to write to it without first 
changing its attributes. Since the class 
of operations controlled by write protec- 
tion includes writing, renaming, and delet- 
ing, a file which is write protected can't 
be deleted by mistake. If I had write pro- 
tected my files I wouldn't have been able 
to delete them without thinking about it. 

It would appear to be impossible to 
ever delete a write protected file, but the 
owner of the file can use the attr command 
to change the attributes. The procedure 
for deleting a write protected file is: use 
the attr command to remove the write pro- 
tection: 

0S9: attr columnS w 



Then delete the file 
command. 



with the normal del 



None of the data files In this directo- 
ry have the execute attribute. They are 
all text files and manifestly not executa- 
ble. OS-9 win only load a file for execu- 
tion if it has the executable attribute. 
The separation of the execute attribute 
from the read attribute makes it possible 
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to create an execute-only file. It would 
oe difficult for someone to copy, dump, or 
disassemble an execute-only file. The 



execute-only attribute is a useful 
for protecting proprietary software. 



trick 



Echo Press carriage return to initiate logon >/TERM 
Echo Press carriage return to initiate logon >/ITl 
Echo Press carriage return to initiate logon >/IT2 
TSMON /ITU 
TSMON /IT2& 
TSMON /TERM 



fiaure 3: 



Sample Startup file 



A particularly sneaky problem is relat- 
ed to the execute attribute. Merging exe- 
cutable files together to form a file with 
all the modules used by some program, or to 
allow a set of popular utilities to be 
loaded compactly under Level Two, will cre- 
ate a file which doesn't have the execute 
attribute. OS-9 won't let you execute or 
load the resulting file. It gives an error 
214, "NO PERMISSION.** The fix for this 
problem is to use the ATTR command to give 
the file the executable attribute. 

If you don't intend to have more than 
one use*" on your computer there is no rea- 
son for you to worry about user numbers. 
If you want to share your computer with 
other people -- either taking turns using 
the computer or using OS-9 as a multi-user 
operating system -- it Is a good idea to 
have a separate user number for each person 
who uses the computer. The best way to set 
your user number is to start the TSMON pro- 
cess in the startup file* The last line in 
the startup file should be something like: 

TSMON /TERM 

TSMON will just sit there until you type a 
carriage return. This may give you the 
impression that something is wrong with the 
:;omputer unless you are ready for this 
■tolid lack of activity. To comfort myself 
: include the 1 i ne : 

ECHO Press carriage return to 
initiate Iogon>/TERM 

before the TSMON command in the startup 
file. It leaves directions on the screen 
after I boot the system. If you are lucky 
enough to own a system large enough to sup- 
port three terminals, the sequence of com- 
mands in Figure 3 should be included in the 
startup file to get everything going. It 
is imoortant to start the last TSMON as a 
foreground task (no &). 

The main business of TSMON Is done by 
the LOGIN command. The LOGIN command uses 
files called password and motd which must 
be in the SYS directory on the same disk 
the default data directory is on (normally 
/DO). The password file includes the user- 
name, user-number, and, optionally, a pass- 
word for each user authorized to use the 
computer. It also includes a lot of infor- 
mation used to set up the environment for 
each user. The full contents of each line 
in the password file are: 

• User Name 

• Password 



• Initial priority 

• Initial execution directory (usually 
• ) 

• Initial data directory (usually .) 

• Initial program to execute (usually 
"she! 1 ") 

The login command prompts for a user-name, 
and. if that user has a password in the 
password file, for a password. If the 
user-name isn't in the password file, or 
the password isn't correct, LOGIN announces 
the mistake and prompts for user name 
aga i n . 

The login command protects each user 
number from unauthorized use by insisting 
on getting a good user-name/password match 
before letting someone use a user-number. 
Many different users can share a user- num- 
ber, allowing them to share files in a 
group, but each user-name can only be asso- 
ciated with one user number, 

If you find a need to change your user 
number in the middle of a session with your 
computer you may be able do it with the 
LOGIN command. The LOGIN command can only 
be used if your default data directory is 
on the same disk the password file is on. 
The LOGIN command needs to read the pass- 
word file. If you protect the password 
file against public read to keep everyone 
from browsing through the passwords, nobody 
but the superuser can use the LOGIN com- 
mand. 

The motd file contains the "message of 
the day." If there is any text in motd it 
will be displayed on the screen each time 
anyone logs on. It can be used to display 
a general greeting, or to give system sta- 
tus information of general interest; e.g., 
"We are running a new release of Pascal 
today . " 

Some tricks can be done with the "ini- 
tial program" in the password file. It is 
possible to specify not only the initial 
program, but also a parameter string for 
it. This opens up extensive possibilities. 
Most operating systems allow a user to have 
the commands in a file (sometimes called a 
user profile or a login command file) exe- 
cuted Bs/ery time he logs on. If you are 
willing to accept some limitations, the 
initial command can be used to do much more 
than start a shell for you when you log on. 
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The simplest possible entry in 
password file might go something like: 

ayname, ,3, 100, . , . , shell 



the 



which would set up a user called myname . 
Myname would have a user number of 3, and 
would be started with a priority of 100. 
His data and execution directories would be 
standard — for most systems /DO and 
/DO/CMDS. Whenever myname logs in a shell 
will be stared for him. 



A somewhat more demanding user can make 
the password file do much more for him. If 
the line in Figure 4 is inserted in the 
password file, it sets up a user with a 
password of xyzzy, gives him non-standard 
data and execution directories, and runs 
FREE and MFREE for him before leaving him 
running a she! 1 . 



hisname, xyzzy, 2, 150. /DO/HISDIR,/DO/BASICX, shell free;inf ree;ex shell 

Figure 4: Password File Entry 



The important thing is that the sequence of 
commands the user wants executed must start 
with the name of the program that will 
interpret the rest of the line. If that 
program is the shell, the last command in 
that shell's parameter string must be an ex 
for whatever command you want to start the 
user with. 

If you want to start a user with a par- 
ticularly long script of commands, perhaps 
enough commands to hold him for an entire 
session, use a shell command file. The 
trick is to have the initial command be 
"shell" with a file name as the parameter. 
If the file isn't in the default data 
directory its full path-name must be speci- 
fied. A sample password file entry might 
go 1 i ke : 



hername,wltrs,5, 130, . 
shell her. cmd* file 



ex shell 



In this case the file "her .cmd. f i le" must 
be in the system default data directory. 
The command file invoked at login is just 
like any other shell command file. The 
important restriction to remember is that 
the shell command file is run by a differ- 
ent shell from the one that the user will 
be using when the command file is finished. 
If you change the directories in the com- 
mand file, those changes will effect only 
the shell running the commands, not the 
shell that will be running after the com- 
mand file is done . 



THE "SUSPEND STATE" 

Microware has added a nifty performance 
enhancement to the latest version of OS-9. 
They discovered that device drivers were 
spending a significant amount of time using 
the FSSEND service request (SR) to communi- 
cate between the interrupt service routine 
for the port and tne rest of the device 
driver. In order to understand why the 
send was done you need some background i n 
the way the OS-9 SCF device drivers work. 
The simplest way to write a device driver 
is to read and write to the port directly 
from the read and write entries of the 
driver, but this requires that the driver 
go into a wait loop while the interface 
chip is performing the operation. A wait 
loop isn't a bad thing if the processor has 
nothing to do until the I/O is complete. 
but, in an environment like OS-9, there are 
likely to be several tasks waiting to get 
done. The •'right" way to write a device 
driver under OS-9 Is to have the actual I/O 
done by an interrupt service routine, and 
have the read and write entries of the 
device driver share queues with the inter- 



rupt routine. 

A character to be written goes to the 
write entry of the device driver which puts 
the character into the write queue if there 
is space for it, or goes to sleep if there 
isn't. The interface chip should be set to 
generate an interrupt whenever it is ready 
to write another character. The interrupt 
service routine will be started every time 
an interrupt is received from the port it 
is responsible for. If the Interrupt was 
an output interrupt, th6 interrupt service 
routine will take a character out of the 
output queue and send it to the port. If 
the device driver is sleeping, waiting for 
an empty slot in the queue to appear, the 
interrupt service routine should send it a 
wakeup signal . 

The procedure for reading a character 
is roughly the reverse of that for writing. 
The queue for input goes from the interrupt 
routine to the read entry and the device 
driver sleeps if a read is done when the 
queue is empty. 

All this sending from the Interrupt 
service routine to the driver is expensive. 
A new system state called the "Suspend 
State" was invented to keep device drivers 
from having to use FSSEND requests to start 
and stop its read and write operations. 
The "suspend state" is a lot like a light 
nap. The process is in the grey area 
between sleep and activity. Suspended pro- 
cesses remain in the active process queue 
where they quickly age to the top of the 
queue, but while the suspend bit is on in 
their process descriptor they can't be 
scheduled. To wake a suspended process up 
just turn the suspend bit off in its pro- 
cess descriptor. The following code would 
wake a suspended process from the interrupt 
routine of a driver: 

Idx (Address of process 

descriptor for the process 
you want to awaken) 

Ida #255-Suspend 

anda P$State,X 

fita P$State,X 

This sequence of instructions can be done a 
great deal faster than a FSSEND. 

A process can suspend itself by turning 
the suspend bit in its process descriptor 
on, then sleeping for a tick. The sleep is 
just a way of giving up the rest of the 
time slice. Even without the FSSleep, next 
time the dispatcher sees the suspended pro- 
cess descriptor it will treat it as sus- 
pended, and won't start it again until the 
suspend bit is turned off. 
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There are a few important limitations directly modifying the process descriptor. 
to the suspend state. The first is that a The last limitation is implicit in the 
process can't get out of suspend state on advantage of suspend state, suspended pro- 
its own. The second limitation is that the cesses stay in the active process queue. 
suspend bit is in the process descriptor They will slow the dispatcher down slightly 
which is the in the system address space. because it will have to pass over them each 
A non-system process has no easy way of time it looks for the next process to run. 
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MORE ABOUT COMPUTERS AT SCHOOL 

I had my first chance to look through a 
microscope when I was very young. My sis- 
ter was deeply ingrossed in the microscopic 
world so I, being a typical younger broth- 
er, hung around and made a pest of myself 
until she showed me what she was working 
on. I couldn't see anything but a blur 
which sometimes faded out altogether. I 
didn't see much point in looking at a blur. 
As years went by I was given my own micro- 
scope, but chemistry sets, and my own 
experiments, were much more interesting. I 
still had trouble getting interested in 
blurs . 



The little story about the microscope 
was intended to address the question: "why 
bother to provide decent computers at 
school?" Students should be given a chance 
to use a computer that they don't have to 
struggle with, and a language that encour- 
ages clear thinking. Kids don't know 
enough to complain about Basic on the 
cheapest computer that can be found. I do, 
so I am complaining for them. 



There were about five more paragraphs 
here about Basic, and the evils of skimping 
on computers for children., but while re- 
reading the ci?^umn.;I .decided that I sounded 
a bit shrill: " Please' forgive the abrupt 
transition, but the smooth conclusion of 
this argument has been pruned with a quick 
block-delete. 



In ninth grade I encountered a real 
microscope for the first time. It was a 
fine old instrument. The teacher treated 
it with' great respect, and insisted that we 
do the same. When I first used it I got a 
surprise that stays with me to this day. 
It was nothing like the microscopes I had 
used before, focusing Jt with the fine 
adjustment knob was no problem, and when 
something was in focus, even a single cell 
or a bacterium, it was very clear. I could 
have happily spent weeks peering through 
the eyepiece at everything I could fit on 
the stage. Eventually the class moved on 
to other things, but I had a new apprecia- 
tion for the world of the very small. 

It is unfair to blame my parents for 
not getting me a high quality microscope 
when I was eight, but it bothers me to 
think of what I missed. I was fascinated 
by what the microscope revealed when I was 
a teenager. The effect would have been 
even stronger if I had been younger. 

My experience with the microscope is 
what makes me keep complaining about the 
tendency of schools to use the lowest qual- 
ity hardware and software they can find. 
The younger the students, the lower the 
quality. The argument is that sophisticat- 
ed hardware and software isn't needed for 
any but the most advanced students. This 
is a serious error . With computers "fool- 
proof" means either trivial, or very 
sophisticated. It requires good hardware, 
and excellent software to deal satisfacto- 
rily with the worst a child can do. The 
kids at most schools are getting the same 
kind of experience with computers I got 
with my early microscope ... only a blurry 
image of what it should be. 

The section of a column I wrote a few 
months ago about computers for schools has 
drawn more comment than any other column I 
have written, maybe more than all of them 
put together. Some people wrote to agree, 
others disagreed. I was glad to hear from 
those who agreed with me, but I was most 
interested in the letters from people who 
took issue with one or more of my points. 
Two of my points drew particularly heavy 
criticism. I calculated the price of an 
imaginary (but realistic) single-user com- 
puter. Several people thought an adequate 
computer could be purchased for less than I 
suggested. I also spent some time wishing 
schools would stop using Basic. It didn't 
surprise me that several readers felt Basic 
was a fine language. 



PIPES 

One of the most useful features of OS-9 
(and UNIX) is the pipe. Pipes by them- 
selves aren't good for much, but if you 
build a good set of "software tools," pipes 
make many tasks surprisingly easy. 

A pipe is a special device which forms 
a connection between two programs such that 
the output from one is directed into the 
input of the other. The shell is a major 
user of pipes. You can ask the shell to 
connect the standard output of one program 
to the standard input of another by putting 
an exclamation point "!" between the com- 
mands. The "!" separates commands like the 
" ; '• and "&" do, but it also redirects the 
output of the command before it into the 
input of the command after it. You could 
get the same effect by using intermediate 
files (Have the first command save its out- 
put into a disk file. When the first com- 
mand ends, run the second command with its 
input coming from the file the first com- 
mand wrote.), but intermediate files are 
neither as fast nor as easy to use as 
pipes . 

When you first start using OS-9, pipes 
won't be of much use to you. For one thing 
they are a bit confusing, but, more impor- 
tant, the standard OS-9 utilities don't 
include many filters. 

A filter is a program which reads from 
the standard input file and writes to the 
standard output file until end of file on 
standard input. They can be used without 
pipes, but, in combination with pipes, a 
good toolbox of filters can be among the 
most useful facilities available under 
OS-9. 

The most elementary filter would simply 
copy bytes from standard input to standard 
output. More advanced filters change data 
on its way through. Some common filters 
sort the data, break it into words, remove 
duplicate lines, count bytes, words, and 
lines, and translate upper case letters to 
lower case. 

It is relatively easy to write special 
filters to solve problems one at a time. 

The trick is to write filters which, in 
combination with others, can do lots of 
useful things. I have a filter which I 
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can "words" (available from the OS-9 Users 
\jroup, but too long for this column) which 
areaks the input up into one word per line. 
I wrote another program which counts the 
number of <CR>s in the input and writes 
that number out when the end of the input 
is reached. I can hook those two programs 
together with a pipe to form a command line 
that counts the words in a file: 

0S9: words <colunmlO ! linect 

That command line feeds columnIO into words 
which slices it up, one word per line. The 
output of words is fed into the standard 
input of linect which responds by giving me 
the number of lines in its input -- the 
number of words in columnIO. I can use 
linect by itself to find the number of 
1 i nes in a file. 

I have written other filters called 
sort and uniq. Sort sorts the standard 
input into the output. Uniq removes dupli- 
cate lines; for example: 

Line One 
Junk Line 
Junk Line 
Junk Line 
Another line 

would come out of Uniq 

Line One 
Junk Line 
Another line 

The command line: 

OS^: words <collO ! sort ! uniq 

would breaV colummo Into words, sort the 
list, remove duplicate lines, and give me a 
sorted list of the words I used in that 
column . 

Since I have written a number of pro- 
grams in assembler and Basic09 for this 
column, I thought I might Include a few 
filters written in Pascal this month. 
ijnfortunately old releases of OS-9 had a 
"law in PIPEMAN which prevented it from 
working with Pascal programs. Pascal 
-ewinds its standard input file when 1t 
-tarts. PIPEMAN wouldn't put up with a 
--ewind with the upshot that filters written 
n Pascal couldn't even get started. The 
easiest language I know for writing filters 
is C, but since C isn't as widely used as 
assembler and BasicOS, I'll Include two 
filters. BWord in Basic09, and CharCt in 
assembler . 

Both BWord and LineCt are crude pro- 
grams. They are nowhere near as efficient 
as they can be. In particular, reading one 
character at a time is Intensely bad prac- 
tice under OS-9. Both of these programs 
could be generalized by using command 
parameters more extensively. 

CharCt counts the number of occurrences 
of the first character in the cor^mand line 
parameter area in the standard input file. 
It could be generalized to look for charac- 
ter strings, or regular express.i c-^s . It 
might also be improved by using more than 
three bytes for the counter. 

The shell always places at least a car- 



riage return in the parameter area passed 
to a program it starts (FORKs). CharCt 
relies on this to give it an easy way to 
default to counting carriage returns in its 
input. If you want to count some other 
character use i t as a parameter on the com- 
mand 1 i ne : 

0S9: charct . <testfile 
would count periods in testfile. 

0S9: charct <testfile 

would count carriage returns in testfile. 

BWord splits the input file into lines, 
one word per line. A word is defined as a 
string of characters between spaces, tabs, 
or carriage returns. It would be more gen- 
erally useful if it would define a word as 
a string of characters delimited by any 
given set of characters. One use of this 
that comes to mind is to divide a file into 
sentences by breaking it at each period. 

BWords should be entered with Basic09, 
and packed. If you have RUNE you can run 
words with a command line like: 

0S9: words <testfile 

which will divide the text in testfile into 
words. If you don't have RUNS you might 
need to use a somewhat longer command line: 

0S9: basic09 words <testfile 

It is easy to spend a great deal of 
effort writing filters you will never use. 
What is needed is a set of general purpose 
tools. There are several sources for good 
ideas for filters. Books about UNIX often 
give descriptions of filters which are com- 
monly used under UNIX. In general, if a 
concept is useful for UNIX it will also be 
for OS-9. The standard programming book. 
Software Tools, by Kernighan and PI auger, 
is an especially good source for ideas and 
algorithms . 



A MORE ADVANCED APPROACH TO 
PIPES 

The Shell uses pipes to connect strings of 
its children together. Any program that 
has access to OS-9 system calls can use the 
same trick the shell uses to make the stan- 
dard output of one of its children feed 
directly into the standard input of 
another, but it is simpler to use pipes as 
a connection between a process and its 
parent. If you need a formatted list of 
processes (the Information given by the 
procs command) you can either mess with the 
process descriptors yourself, or use a pipe 
to intercept the output from procs. 

If your algorithm can be divided Into 
several sections that communicate in only 
one direction (Say, one section collects 
information, the second sorts it, and the 
third formats a report.), the job can easi- 
ly be done by three separate processes dis- 
patched from the command line with the 
shell managing the pipes. If the steps 
aren't fixed (Perhaps you either report or 
update a file depending on the date.), it 
might be easier to deal with the pipes 
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yourself. This type of thing requires 
pipes to be defined for each new process's 
standard input path. 

Using a pipe as the standard output 
path from a child process is useful for 
more than intercepting the output from sys- 
tem utilities. The first experiments to 
try with this mechanism are with system 
utilities, but the most interesting appli- 
cations are with processes designed espe- 
cially for this use. An example might be a 
program which uses a process attached via a 
pipe to get data from a remote computer. 
The process at the end of the pipe would 
dial the remote computer up, go through the 
logon formalities, and deal with any commu- 
nication protocols. The main process would 
just read distilled information from the 
pipe. 

All three standard paths can be used 
for pipes. I haven't thought of a use for 
all three paths, but a combination of input 
and output paths is useful. The child pro- 
cess is given work to do through its stan- 
dard input path and returns the results of 
its work through its standard » or error, 
output path. The parent process gives the 
child work through one pipe and at an 
appropriate time (maybe much later) gets 
the results by reading from a different 
pipe. 

A FORKed process inherits the three 
standard paths of its parent. If it were 
OK to give up after setting up pipes, the 
way to set them up would be to close the 
standard files, and create three pipes, one 
each for path one, two and three. The 
instructions to open a pipe in the standard 
input path would be: 

Pipe fcs '7PIPE" 
Ida #0 std in 
0S9 HCLOSE 
leax Pipe,PCR 
Ida #UPDATE, 
0S9 I$OPEN 

New paths always take the lowest available 
path number so the pipe would fall into 
path zero. A process forked from this pro- 
cess would inherit its standard paths 
including the pipe in path zero. The new 
process would treat its path as a normal 
standard input path. Characters written 
into the pipe by the parent would be read 
by the child. 

If a pipe is opened with no process 
FORKed to use it, the pipe will act like a 
queue. A process can write a limited num- 
ber of bytes into the pipe and read them 
out again in the same order they were writ- 
ten. If there isn't room in the queue for 
the data from a write to be stored the pro- 
cess doing the write will be put to sleep 
until there is space to complete the write. 
If the process that reads from the pipe is 
the same one that is sleeping until the 
queue empties a little there is a deadlock. 
A deadlock can only be avoided, or broken 
by some outside agency . . . the human at the 
terminal for instance. Because of this 
deadlock problem, and the small size of the 
queue in the pipe, the idea of using a pipe 
as a queue is only a novelty. 

The example of communications via pipes 
that I have invented is a BasicOS program 



that prompts for pairs of coordinates, and 
passes the pairs to a C program which 
"rasterizes" the lines between the points 
defined by the coordinates. The BasicOS 
program passes as many pairs as it likes to 
the C program, then closes the path it has 
been writing the data to. When the parent 
closes his end of the pipe the child will 
get an end-of-file. The C program sends 
the raster i zed data back through its stan- 
dard output path. This data consists of a 
string of zeros and ones indicating where 
dots should be placed on each horizontal 
line in order to draw the vectors received 
as input. 

Rasterizing vector graphics information 
is a particularly good application for a 
separate process. In a Level Two system 
each process can use an entire address 
space of almost €4K . The size and resolu- 
tion of the graph that is produced depends 
on the amount of memory available for the* 
bit map of the graph. I have a version of 
rast that uses 46K for its bit map and can 
generate an 8"X8" graph on my Ok i data at 72 
dots per inch. I am not very experienced 
with graphics; there is probably a much 
better way to raster ize data than what I 
used. My program seems too complicated for 
such a simple task, but it works. 

It is particularly important to keep 
track of interactions between two processes 
communicating via pipes. If the processes 
ever get into a situation where both are 
waiting for input from a pipe leading to 
the other process, they will be stuck until 
you free them by killing one of the pro- 
cesses . 

The Important part of this system of 
programs is an assembly language subroutine 
for the BasicOS program. The subroutine is 
descended from the StrtTask subroutine I 
published months ago, but has been enhanced 
to open pipes to the new process. The 
I$DUP call is used to preserve the standard 
input and output files of the Basic09 pro- 
gram while paths zero and one are turned 
into paths then back into whatever they 
were before. 



Installation 

This system of programs is written in three 
separate languages. If you don't have C it 
should be fairly easy to translate rast 
into BasicOS, but if you rewrite rast in 
BasicOS be certain that you don't try to 
fork it directly. BasicOS should be the 
program you fork; rast should be the param- 
eter. If you want to keep the old StrtTask 
around, rename either it or the new one. 
Grapher should be typed into BasicOS and 
saved- Particularly if you are using Level 
One, you should pack Grapher and use RunB 
to save memory. In Summary: 

• Enter StrtTask and rast.c using an 
edi tor 

• Assemble StrtTask 

• Compi le rast . c 

• Enter Grapher using BasicOS 

• Save the source 
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If you intend to run Grapher from the 
command line add the line: BYE to the 
end of Grapher and Pack Grapher 

Run Grapher which will load StrtTask 
and rast from the execution directory 



Operation and Modification 

Grapher will prompt for pairs of coordi- 
nates. After each pair is entered it will 
ask you to verify that you want to plot 
that line. Be careful with this. There is 
no validation in any part of this system. 
There is no reason it shouldn't be there 
either . Please add enough error checking 
to make you comfortable if you intend to do 
more than play with this program a little. 
If you try to draw a line way off Into the 
wild blue yonder your computer will give it 
a good try, mashing everything in its way. 
After you enter the last pair of coordi- 
nates respond to the (y,n.d) prompt with D. 
The D response sends the last pair to rast 
and charts the response from rast on the 
screen. I like to draw conservative pat- 
terns like the one given by the input in 
figure Figure 5. 



79 23 
23 79 
23 
79 

11 79 11 



39 39 23 

Figure 5: 



Sample Input for rast 
program 



Rast is set up to rasterize a 80 by 24 
graph. That is the size of a standard ter- 
minal, but if you want to deal with larger 
or smaller graphs, change VDIMENSION to the 
number of vertical dots in the graph, and 
HDIMENSION to the number of horizontal 
dots . 

Pipes are a powerful tool for interpro- 
cess communications. They can be used with 
good effect to solve almost any interpro- 
cess communication problem If the connec- 
tion can be made. The worst problem with 
pipes is that they can only be used between 
processes that are very closely related 
(between siblings, or parent/child). There 
is also a performance problem under Level 
Two; not only is there the cost of a system 
request per transfer, but OS-9 has to move 
the characters from one address space to 
another -- taking a surprising length of 
time. If you feel ambitious you will find 
nat it is possible to make a major per- 
ormance improvement to rast by using a 
;:ompression algorithm on its output. 



descendant of 
chance that I 
viewpoint of a 
the future. I 



WELCOME COCO 

I have been reading messages in the COCO 
special interest group on CompuServe. It 
sounds like Microware put a real version of 
OS-9 on that little machine. I am serious- 
ly impressed with the reality of a very 
inexpensive computer with a UNIX-like, mul- 
titasking, even -- if I may stretch a point 
-- multi-user operating system. There may 
be a number of interesting ways to inte- 
grate COCOs with each other and with larger 
OS-9 systems to get a bargain version of 
advanced distributed computing. It may not 
be too much to hope for that Tandy will 
find a way to put OS-9 Level Two on some 
the COCO. There is some 
will be able to take the 
COCO user in this column in 
haven't made up my mind yet, 
but I need a Level One system, and the Col- 
or Computer may be the way to get one. I 
would appreciate advice. 



THE USERS GROUP 

The executive committee of the OS-9 Users. 
Group has met twice since the annual meet- 
ing (I am writing this in November). We 
have struggled with various issues and 
defined assorted policies, mostly rather 
dull. Very likely by the time this column 
is printed the members will have received a 
newsletter, and everyone will have seen 
information in this and other magazines. 
Right now our software library is ready to 
go. I know it has good stuff in it; sever- 
al programs of mine are part of the collec- 
tion. Our plan is to give a standard 
selection of software from the library to 
the existing membership and to each new 
member. The other programs in the library 
will be available for small amounts of mon- 
ey, or software contributions. The address 
of the Users Group is; 

OS-9 Users Group 

PO Box 8027 

Des Moines, Iowa 

50301 
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BWORD 



PROCEDURE 
0000 
0036 
006C 
00A2 
00D8 
OODF 
00E6 
00F5 
OOFB 
0102 
0109 
0110 
0116 
0118 
0122 
012B 
0147 
014D 
0153 
0157 
0163 
0165 
0169 
0185 
0189 
018F 
019B 
019D 
019F 
01A3 
01A5 
OIBE 
01C5 
OICB 
01D7 
01D9 
OIDD 
OlEO 
OlFB 
OlFD 



100 



bword 

ri' *\ 

v^ Filter to divide input into words. One word per ''^) 
('^ line, *) 

DIM chr:BYTE 

DIM inword: BOOLEAN 

DIM StdOut,StdIn,StdErr:INTEGER 

ON ERROR GOTO 100 

StdIn-0 

StdOut=l 

StdErr=2 

inword=FALSE 

LOOP 

GET #StdIn,chr 
IF inword THEN 

IF chr-ASC(" ") OR chr=9 OR chr=13 THEN 
inword^FALSE 
WRITE #StdOut 
ELSE 

PRINT #StdOut,CHR$(chr); 
ENDIF 
ELSE 

IF chr-ASC(" ") OR chr«9 OR chr-13 THEN 
ELSE 

inword=TRUE 

PRINT #StdOut,CHR$(chr); 
ENDIF 
ENDIF 
ENDLOOP 
BYE 

REM end of file handler 
DIM er mum: INTEGER 
errnuin«=ERR 
IF errnuin=211 THEN 

BYE 
ELSE 

ON ERROR 

PRINT #StdErr, "Error Number: "; errnum 
BYE 
ENDIF 
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CHARCT 



Microware OS-9 Assembler 2.1 11/08/83.22:55:20 
CharCt - Count a occurances of a specified character 



Page 001 



00001 

00002 

00003 

00004 

00005 

00006 

00007 

00008 

00009 

00010 

00011 

00013 

OOOIA 

00015 

00016 

00017 

00018 

00019 

00020 

00021 

00022 

00023 

0002A 

00025 

00026 

00027 

00028 

00029 

00030 

00031 

00032 

00033 

0003A 

00035 

00036 

00037 

00038 

00039 

00040 

OOOAl 

00042 

00043 

00044 

00045 

00046 

00047 

00048 

00049 

00050 

00051 

00052 

00053 

00054 

00055 

00056 



* 
* 



CharCt 



NAM CharCt 

TTL Count a occurances of a specified character 

Written 1 November 83 * 
Last Modified 5 November 83 * 
A filter to count occurances of any specified* 
character in the standard input. If no '"' 
character is specified, default to counting 
carriage returns. 



* 

-A 



0011 

0081 

0000 87CD009A 

0000 

0003 

0004 

0005 

OOOB 

OOOC 

00D4 

OOOD 43686172 

0013 01 

* 



Type 
Revs 

Count 

InChr 

TstChr 

OutStr 

CR 

Memsize 
CharCt 



IFPl 

ENDC 

set 

set 

MOD 

rmb 

rmb 

rmb 

rmb 

rmb 

rmb 

equ 

f cs 

fcb 



Prgrm+Objct 

ReEnt+1 

pgml en , CharCt , Type , Revs .Entry , Mems ize 



1 
1 
6 
1 
200 

/CharCt/ 

1 



stored in BCD 



for a 
Stack 



CR 



version 



* 
* 



At entry: 

U and DP point at local storage. 
X points at the parameter area. 



0014 
0014 
0016 
0018 
OOIA 
OOIC 
OOIE 
0020 
0024 
0024 
0026 
0029 
002B 
002D 
002F 



0031 
0033 
0035 
0036 
0038 
003A 
003C 
003D 



OFOO 
OFOl 
0F02 
A684 
9704 
3043 
108E0001 

8600 

103F89 

251E 

D603 

D104 

26 F3 

* 



8601 

9B02 

19 

9702 

8600 

9901 

19 

9701 



Entry 



Loop 



clr 

clr 

clr 

Ida 

sta 

leax 

Idy 

Ida 

0S9 

bcs 

Idb 

cmpb 

bne 



Count 

Count+1 

Count+2 

,X 

TstChr 

InChr , U 

#1 

P. 
I$READ 

Quit 

InChr 

TstChr 

Loop 



Increment Count 



Ida 

adda 

daa 

sta 

Ida 

adca 

daa 

sta 



tl 



ount+2 
Count+2 
Count+1 
Count+1 






characters to read 
std in 
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00057 

00058 

00059 

00060 

00061 

00062 

00063 

00064 

00065 

00066 

00067 

00068 

00069 

00070 

00071 

00072 

00073 

00074 

00075 

00076 

00077 

00078 

00079 

00080 

00081 

00082 

00083 

00084 

00085 

00086 

00087 

00088 

00089 

00090 

00091 

00092 

00093 

00094 

00095 

00096 

00097 

00098 

00099 

00100 

00101 

00102 

00103 

00104 

00105 

00106 

00107 

00108 

00109 

00110 

00111 

00112 

00113 

00114 

00115 

00116 



003F 8600 
0041 9900 

0043 19 

0044 9700 

0046 4F 

0047 20DB 



Ida 

adca 

daa 

sta 

clra 

bra 




ount 



Count 
Loop 



std in 



If we reached EOF print the total count and 


* 


exit. 


it 


If some other caused us to stop. Return 


A 


with an error code. 





0049 
0049 
004B 
004D 
004F 
0051 
0053 
0055 
0057 
0059 
005B 
005D 
005F 
0061 
0063 
0067 
0069 
0069 
006B 
006D 
006F 
0071 
0073 
0073 
0075 
0077 
0079 
007B 

007D 
007F 
0082 
0083 
0083 
0086 
0086 
0088 
0089 
008A 
008B 
008C 
008E 
0090 
0092 
0094 
0096 
0097 
009A 



C1D3 

2636 

3045 

9600 

8D33 

9601 

8D2F 

9602 

8D2B 

3045 

960a 

8A80 

970A 

108E0007 

8630 

A184 
2606 
313F 
3001 
20F6 

86 OD 
970B 
960a 
847F 
970A 

8601 

103F8C 

5F 

103F06 

1F89 

44 

44 

44 

44 

8630 

A780 

C40F 

CB30 

E780 

39 

A1D953 



Quit 



FndLen 



OutPut 



Exit 
Cnvt 



cmpb 

bne 

leax 

Ida 

bsr 

Ida 

bsr 

Ida 

bsr 

leax 

Ida 

ora 

sta 

Idy 

Ida 

cnpa 

bne 

leay 

leax 

bra 

Ida 

sta 

Ida 

anda 

sta 

Ida 
0S9 
clrb 



Pgnlen 



tfr 

Isra 

Isra 

Isra 

Isra 

adda 

sta 

andb 

addb 

stb 

rts 

EMOD 

equ 



#E$EOF 

Exit 

OutStr.U 

Count 

Cnvt 

Count+1 

Cnvt 

Count+2 

Cnvt 

OutStr,U 

OutStr+5 

#580 

dutStr+5 

Po 

.X 

OutPut 
-1,Y 
1,X 
FndLen 

gOD 

OutStr+5 

#$7F 

6utStr+5 



fi 



$WRITLN 



0S9 F$Exit 



A,B 



*x5 



mark last position in OutStr 
set carry bit 

length 



decrease length 

<CR> 

clear the carry bit out 

std out 

clean up for exit 



shift the high order nible into low 



convert to ASCII digit 

remove high order nyble 
convert to ASCII digit 
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GRAPHER 

PROCEDURE Grapher 

0000 DIM process No,Comp Code, Opt Size, Lang TypeiBYTE 

0013 DIM Farm LrTNTEGER - - - 

OOIA DIM InPipe,OutPipe:BYTE 

0025 DIM ch:STRINGllJ 

0031 DIM YNrSTRING 

0038 DIM xl,yl,x2,y2: INTEGER 

OOAB DIM name: STRING 

0052 DIM Farms: STRING [20] 

005E (* ^^ 

009C O; Set up to call StrtTask which will fork the named '^ 

OODA (''^ module, passing it the parameter string in Farms. '* 

0118 I'' * 

0156 name-*'rast*' 

0161 process No'^0 

0168 Opt_Size=0 

016F Lang Type*^$ll \i^ attributes of forked module (object code, program) 

OlAC Farms=^^^+CHRS(13) 

01B7 Farm L"LEN(Farms) XC'^ The length of the parameters must be correct 

OlEF ('J " *) 

0230 0' Call assembler subroutines to Fork and wait for the started *) 

0271 (* process *) 

02B2 r^ ^ *) 

02F3 RUN StrtTask (name, process_No,Lang_Type, Farm L, Farms ,Opt_Size 

,InFipe,OutFipe) 

0361 (^^ Write data for "rast" into path //InPipe which *) 

03A2 (^^ corresponds to the standard input path for rast *) 

03E3 0^ *) 

0A2A PRINT *'Enter the endpoints of lines you want drawn. X must be in" 

0461 PRINT "the range 0..79. Y must be in the range 0..23.*' 

0493 LOOP 

0495 INPUT "Enter X Y coordinates for the ends of a line: ",xl 

04D7 PRIN/"The ^line will be drawn between ("; xl; ","; yl; ") and (" 

' x2' " *'• y2' ")'* 
0521 INPUT "OK ? (Yes, No, Done) : ",YN 
053E YN=LEFT$(YN,1) 
0549 IF YN«"y" OR YN="Y" THEN 
055E PRINT #InPipe,"l",xl,yl,x2,y2 
0578 ENDIF 

057A EXITIF YN-"d" OR YN«"D" THEN 
058F PRINT #lnPipe,"l",xl,yl,x2,y2 

05 A9 ENDEXIT 
05AD ENDLOOP 

05B1 ON ERROR GOTO 100 

05B7 CLOSE #InPipe 

05BD 0'^ '^) 

05FE ("^ When #InPipe is closed rast will get an end-of-file *) 
063F ('*' on its standard input path. *) 

0680 (* *) 

06C1 LOOP 

06C3 (^ *) 

0704 (^ Read from //OutPipe (which corresponds to rast's standard *) 
0745 0^ output until end-of-file on that path. The end-of-file *) 
0786 (* indicates that the other end of the pipe has been closed *) 
r7C7 (* (in this case rast has ended). *) 

B08 V^ *) 

49 GET #0utPipe,ch 

.53 IF ch«"0" THEN 
..B60 PRINT " "; 

0866 ELSE 
086A PUT #l,ch 
0873 ENDIF 
0875 ENDLOOP 

0879 100 

087D ON ERROR 

0880 CLOSE #OutPioe 

0886 RUN WaitTasklprocess No,Comp Code) 

0895 IF Comp Code<>0 THEN" 

08A1 PRINr""Completion code for "; name; " # "; process_No; " was " 

; Comp Code 
08D4 ENDIF 
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00001 

00002 

00003 

OOOOA 

00005 

00006 

00007 

00008 

00009 

00010 

00011 

00012 

00013 

00014 

00015 

00016 

00017 

00018 

00019 

00020 

00021 

00022 

00023 

00024 

00025 

00026 

00027 

00028 

00029 

00030 

00031 

00032 

00034 

00035 

00036 

00037 

00038 

00039 

00040 

00041 

00042 

00043 

00044 

00045 

00046 

00048 

00049 

00050 

00051 

00052 

00053 

00054 

00055 

00056 

00057 

00058 

00059 

00060 

00061 

00062 

00063 

00064 

00065 

00066 

00067 

00068 

00069 

00070 

00071 

00072 

00073 



ttl Start a subtask (called from Basic09) 

nam StrtTask 

* 



* 
* 

it 
A 
Vt 
* 
* 
* 
* 
* 
* 
* 
* 

* 

* 
* 
* 

* 

* 
* 
* 
* 



StrtTask is a subroutine for Basic09. 
Start a named module as a subtask. 
Let the new task run asynchronously. 
Open pipes to the modules standard in and standard* 
out paths. 

Return the new tasks process number, the path 
numbers for the pipes, and the condition code 
from the Fork. 
Calling sequence: 

run StrtTask (Name, Process_Num, Lang_Type, 
Param L, Faram, Opt size 
InPipeN, OutPipeN) ~ 
Name is any length, but has a valid terminator 
(high bit set on last byte, or delimiter after 

Frocess_Num byte field, process number of new task. 
Lang Type byte field, language/tj^e byte for 

forced module. 
Param_L, integer field, length of parameter area. 
Faram field of any type, parameter area to be 

passed to forked process. 
Opt_Size byte field, optional data area size in 

pages. 
InPipeN, integer field, path number 
OutPipeN, integer field, path number 
Frocess_Num, InPipeN, OutripeN, and Return_Codc 
are altered by StrtTask, no other parameters are. 



* 
* 
* 
* 
* 
* 

* 

t)* 



* Offsets 



IFPl 
ENDC 

to arguments 



0002 
0004 
0008 
OOOC 
0010 
OOIA 
0018 
OOIC 
0020 
0021 
0081 
0000 
0001 
0000 
OOOD 
0015 
001 A 
OOIB 
OOIB 
OOID 
0021 



87CD00B1 
53747274 
2F504950 
01 

EC62 

10830008 

10260083 



ACount 

ModuleN 

ProcNum 

ModType 

ParmLen 

Parms 

MDatSize 

InPipeN 

OutPipeN 

Type 

Revs 

Stdin 

StdOut 

StrtTask 
Pipe 

SEntry 



equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
set 
set 
equ 
equ 
mod 
fcs 
fcs 
fcb 

Idd 

cnpd 

Ibne 



2 

4 

8 

12 

16 

20 

24 

28 

32 

SBRTN-^OBJCT 

REENT+1 



1 

TLen, StrtTask, Type, Revs, SEntry,0 

/StrtTask/ 

^VPIPE" 



version 



ACount, S 
BadExit 



get paraxn count 
are there 8 paratns? 
no; leave now. 






Set up Pipes for StdIn and StdOut. * 

The procedure is: " 

Dup the stdin and stdout paths to save them. * 

Close stdin and stdout. * 
Open /PIPE twice. One will be path the next* 

path 1. * 

Fork the new process. * 



0000 
0001 
0002 



Offsets from S for local storage 
DStdIn equ 
DStdOut equ 1 
LocalSiz equ 2 
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:007A 
00075 
-10076 
00077 
00078 
00079 
00080 
00081 
00082 
00083 
00084 
00085 
00086 
00087 
00088 
00089 
00090 
00091 
00092 
00093 
00094 
00095 
00096 
00097 
00098 
00099 
00100 
00101 
00102 
00103 
00104 
00105 
00106 
00107 
00108 
00109 
00110 
00111 
00112 
00113 
00114 
00115 
00116 
00117 
00118 
0C;i9 
00120 
00121 
00122 
00123 
00124 
00125 
00126 
00127 
00128 
00129 
00130 
00131 
00132 
00133 
00134 
00135 
00136 
00137 



0025 
0027 
0029 
002C 
002E 
0030 
0032 
0035 
0037 



327E 

8600 

103F82 

257D 

A7E4 

8601 

103F82 

2574 

A761 



leas 
Ida 



0039 8600 
003B 103F8F 
003E 256B 

0040 8601 
0042 103F8F 
0045 2564 

0047 308DFFCA 
004B 8603 
004D 103F84 
0050 2559 

?* This will 

0052 308DFFBF 
0056 8603 
0058 103F84 
005B 25AE 

* This will 
005D 103F82 
0060 2549 
0062 A7F822 

0065 8600 
0067 103F82 
006A 253F 
006C A7F81E 



0S9 


I$Dup 


bcs 


BadExit2 


sta 


DStdln.S 


Ida 


#StdOut 
I$Dup 


0S9 


bcs 


BadExit2 


sta 


DStdOut,S 


Ida 


#StdIn 


0S9 


I$Close 


bcs 


BadExit2 


Ida 
0S9 


#StdOut 
I$Close 


bcs 


Bad£xit2 


leax 


Pipe.PCR 
#ufDAT. 
ISOpen 
Bad£xit2 


Ida 


0S9 


bcs 


be path 




leax 


Pipe.PCR 
#UfDAT. 
ISOpen 
BadExit2 


Ida 


0S9 


bcs 


be path 1 




0S9 


ISDup 


bcs 


BadExit2 


sta 


[LocalSiz 



-LocalSiz.S make space for temp storage 
^Stdln 

Dup Stdin 



Dup StdOut 

Close StdIn 
Close StdOut 



Open a pipe in path 



Open a pipe in path 1 



Dup it 



Ida #StdIn 

0S9 ISDup Dup it 

bcs Bad£xit2 

sta [LocalSiz+InPipeN,S3 



006F 
0071 
0075 
0078 
007B 
007E 
0081 
0083 



0086 
0088 
008B 
008D 
0090 
0092 
0095 
0097 
009A 
009C 
009F 
OOAl 
00A4 
00A6 
00A7 



AE66 

10AEF812 

A6F80E 

E6F81A 

EEE816 

103F03 

2528 

A7F80A 

is ^« 



Idx 
Idy 
Ida 
Idb 
Idu 
0S9 
bcs 
sta 



8600 

103F8F 

8601 

103F8F 

A6E^ 

103F82 

A6EA 

103F8F 

A661 

103F82 

A661 

103F8F 

3262 

5F 

39 



LocalSiz+ModuleN,S address of module name 
.LocalSi2+ParmLen,S] length of parameters 
,LocalSi2+ModType,S] type of module to invoke 
.LocalSiz+MDatSize,SJ optional data area size 

LocalSiz+Parms, S pointer to parameters 

F$Fork start tne new process 

BadExit2 

[LocalSiz+ProcNum,S] save new process number 



Restore 
paths 



the original 
and 1 . 



stdin and stdout files to 



Ida 

0S9 

Ida 

0S9 

Ida 

0S9 

Ida 

0S9 

Ida 

0S9 

Ida 

0S9 

leas 

clrb 

rts 



StdIn 
$Close 
#StdOut 
ISClose 
DStdIn,S 
I$Dup 
DStdIn,S 
I$Close 
DStdOut,S 
I$Dup 
DStdOut,S 
I$Close 



Close StdIn and StdOut 



path number of duped stdin 
dup it into path 

and close it 

path number of duped stdout 

dup it into path 1 

and close it 



LocalSiz, S clear stack 
clear carry 
return 
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00138 

00139 

00140 

00141 

00142 

00143 

00144 

00145 

00146 

00147 

00148 

00149 

00150 

00151 

00152 

00153 

00154 

00155 

00156 

00157 

00158 

00159 

00160 

00161 

00162 

00163 

00164 

00165 

00166 

00167 

00168 

00169 

00170 

00171 

00172 

00173 

00174 

00175 

00176 

00177 

00178 

00179 

00180 

00181 

00182 

00183 

00184 

00185 

00186 



00A8 
00A8 
00A9 
OOAB 
OOAB 
OOAD 
OOAE 
OOBl 



43 

327E 

3262 

39 

239951 



BadExit 



BadExit2 



TLen 



-k 

-k 
-k 
* 



coma 
leas 

leas 

rts 

EMOD 

equ 

ttl 

nam 



set carry 
-LocalSiz,S dummy push 

LocalSi2,S clear stack 
return 



Wait for a (child) process to complete 

WaitTask 

-k 



WaitTask is a subroutine for Basic09 

Wait for the a child process to complete. 

Return the process ID of the process that completed^ 

in parameter one. 

Return the competion code of the process 

in parameter two» 

This subroutine will wait using no CPU time until 

a child process completes. 

If a child completed just before WaitTask was 

called, it will return almost imroediatly. 

If there are no children, an error will be returned 

with a process number of 0. 

Calling sequence: 

RUN Wait-Task (Process^No, Comp^Code) 
both process_no and Comp_Code are BYTE variables. 



0021 
0081 
0000 
OOOD 
0015 
0016 
0016 
0019 
OOIB 
OOIF 
0021 
0024 
0026 
0029 
002C 
002D 
002D 
002E 
002E 
002F 
0032 



87CD0032 
57616974 
01 

6FF804 

EC62 

10830002 

260C 

103F04 

2508 

A7F804 

E7F808 

39 

43 

39 
4C34C4 



Type 
Revs 

WaitTask 

WEntry 



WBExit2 
WBExit 

WLen 



set 
set 
mod 
fcfi 
fcb 

clr 

Idd 

cmpd 

bne 

0S9 

bcs 

sta 

stb 

rts 

coma 

rts 
EMOD 
equ 
end 



00000 error (s) 

00000 warning (s) 

$00E3 00227 program bytes generated 

$0000 00000 data bytes allocated 

$218B 08587 bytes used for ssnnbols 



SBRTN+OBJCT 

REENT+1 

WLen,WaitTask, Type, Revs , WEntry, 

/WaitTask/ 



[4,S] 
2.S 

WBExit2 
F$Wait 




edition 

zero the process ID 

param count 

if not exactly 2 params then 

the caller is making a bad mistake 

wait for a child 

return the process ID 
return the completion code 
return 

set carry 

return 
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iflAST 

9 November 1983 0:1A Rasterizing Program Page 1 

1 //include <stdio.h> 

2 //define VDIMENSION 24 

3 //define HDIMENSION 80 

4 //define BYTES HDIMENSION/8 

5 //define TRUE 1 

6 //define FALSE 

8 '' Data Structure * 

9 * The rasterized data is kept in an array of bits. ''^ 

10 * The Setbit and BitSet routines are responsible for * 

11 ^^ determining which bit correspondes to each * 

12 * position. They also are the only procedures with ^ 

13 * access to the ^*bit" array. * 

15 mainO 

16 T 

17 int xl, yl, x2, y2; 

18 int i; 

19 char op; /^ takes values of L Line (n,n,n,n) 

20 C Circle (n,n,0,0) 

21 S Spline (open) (n,n,n,n,n,n) 

22 E Spline (closed) (n,n,n,n,n,n) 

23 .V 

24 register int j; 
25 

26 while (scanf("*i:c %d %6 %d •^d",&rop, &xl,&ryl, &x2,&ry2) !- EOF) 

27 /* Ignore "op" for now 'V 

28 if (xl < x2) 

29 draw(xl,x2,yl,y2) ; 

30 else 

31 draw(x2,xl,y2,yl) ; 
32 

33 for , (i*VDIMENSION-l ; i>«0; i— ) 

34 { 

35 for (j»0;j<HDIMENSION:j++) 

36 putchar(bitset(j,i) ? '1' : *0'); 

37 ^ printf("\n"); 

38 } 

39 return; 

40 J /^ end of main */ 
41 

42 draw(xl,x2,yl,y2) 

43 int xl, x2, yl, y2; 

44 { 

45 int deltay, deltax, x, y, dy, dx; 

46 float e, slope; 

47 register int i; 
48 

49 deltay - y2-yl; 

50 deltax « x2'-xl; 

51 X - xl; 

52 y = yl ' 

53 if ((deltax " deltay) LL (deltay " 0)) 

54 { /" special case — draw a point */ 

55 plot(x.y); 

56 , return; 

57 } 
58 

59 if (deltax > deltay) 

60 { ^ 

61 if (deltax " 0) 

62 { /^ prevent division by zero */ 

63 y « (yl <= y2) ? yl : y2: 

64 for (i-0;i<«((deltay >» O) ? deltay : -deltay) ; i++) 

65 plot(x,y++); 

66 ^ return; 

67 } 

68 slope = (float)deltay/(float)deltax; 

69 if Xslope >- 0) 

70 { 

71 e = slope-0.5; 

74 else 

75 I 

76 e «= slope+0.5; 

77 , .y.-l; 
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152 
153 
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79 for,(i-0; i<-deltax; i++) 

80 { /* actually draw the line */ 

81 plot(x,y); 

82 If (((slope > 0.0) W (e>0.0)) 

83 ((slope < 0.0 ) && (e<0.0)))" 

85 y += dy; 

86 . e -= dy; 

87 } ^ 

88 X++; 

89 e +•= slope; 

90 } f* actually draw the line */ 

92 else 

93 I 

94 slope - (float)deltax/(float)deltay; 

95 if Tslope > 0) 

96 { 

97 e • slope-0.5; 

98 , dx - 1; 

99 } 

100 else 

101 1 

102 e - slope+0.5; 

103 , dx - -1; 
lOA } 

105 for (i^O; i<-deltay; i++) 

106 { /* * 

107 * draw a, line with slope greater than one * 

108 * for this type of line y needs to be * 

109 '• incremented more frequently than x. * 

111 plot(x,y); 

112 if (((siop( 



113 

llA X += dx; 

115 , e — dx; 

116 } 

117 y++; 

118 , e += slope; 

119 , } 

120 } 

121 , return; 

122 } /* end of draw */ 
123 

124 plot(x,y) 

125 int x,y; 

126 { 

127 setbit(x,y); 

128 , return; 

129 } , w , 
131 static char bit [VDIMENSION] [BYTES] ; 
132 

133 setbit(x,y) 

134 int x.y; 

135 { 

136 int temp=l; 

137 register int tx; 

1 oc 

139 temp = temp « (x%8) ; 



(((slope > 0) &.& (e>0)) || ((slope < ) && (e<0))) 



140 tx = x/8; 

141 bit[yj [tx] « bit[y] [tx] 



142 ^ return; 

143 } 
144 

145 bitset(x.y) 

146 int x,y; 

147 1 

148 int temp=i; 



temp; 



149 , , 

150 temp -temp << (x%8) ; 

151 , return(bitly] [x/8] & temp^; 
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CUL.UHM KLISVKW — THE OS- 9 
1/0 SYSTEM 



05-9 uses a modular I/O system ctesigned for 
simplicity and flexibility. Because of 
this modularity an exceptionally ambitious 
user could write a new I/O subsystem and 
graft it into OS-9 without making any 
changes to the rest of the operat i ng sys- 
tem . But there are other aspects of the 
I/O system which don't require any program- 
ming to exploit, and so useful that new 
OS-9 users should play with them as soon as 
possible . 



THE UNIFIED INPUT/OUTPUT SYSTEM 

Each OS-9 process has three standard paths 
(files) open when it starts. Path is 
called standard input, Path 1 is standard 
output, and path 2 is standard error. It 
is possible for a program to close these 
paths and re-open them for its own purpos- 
es, but most programs leave them open and 
use them as one might think they should be 
used. 

The standard input path usually reads 
from the keyboard (terminal), and is used 
as the primary source of input from the 
user. Programs can and often do open other 
input files, sometimes the majority of the 
input is from some path other than standard 
input, but standard input is by convention 
the path used for communication with the 
user . 

The standard output path typically 
writes to the screen (terminal), and is 
used for routine output to the user. Every 
character that appears on your screen prob- 
ably came from a standard output path. 

The standard error path is seldom used. 
By convention it is used for error messag- 
es. Normally the standard error path is 
directed to the screen together with the 
standard output path. The rationale for 
having separate paths for routine output 
and error messages rises from a special 
characteristic of the standard paths. Each 
of the paths can be directed wherever the 
user wishes before a program is started. 
This can prove useful when it is convenient 
to have different things done with error 
messages than with the rest of the output 
of a program. 

The standard paths are open when a pro- 
gram starts because they are inherited from 
the process that started it, in most cases 
the shell. The shell takes advantage of 
this ability to pass its standard paths on 
to the programs it starts to change the 
paths from the standard (all to the termi- 
nal) to any other disposition a user might 
specify. 

Options on a shell command line indi- 
cate to the shel 1 what needs to be done to 
the standard paths. The options are 
">xxxxx*' for "redirect standard output to 
xxxxx," "<xxxxx" for "redirect standard 
input to xxxxx." and '•>>xxxxx" for "redi- 
rect standard error to xxxxx." If any stan- 
dard path is not redirected it is simply 
inherited from the shell; It usually goes 
to the terminal . 



The ability to redirect the standard 
paths is called device Independent I/O 
because paths can be directed to any 
device, not just another device of the same 
type as the default device for the path. 
The power of this feature is easiest to see 
with a few examples: 

0S9: list filename 

Is a command with no redirection. It lists 
the contents of the file called "filename" 
on the screen through the standard output 
path. 

0S9: list filename >/P 

lists the contents of filename on the 
device called /P, usually the printer. The 
single ">" at the end of the command tells 
the shell to redirect the standard output 
to t he file whose name foil ows t he > . I 
can't think of any reason for someone to 
want to put the output of the list command 
into a disk file, but: 

0S9: list filename >lstfile 

does just that. It puts the output of the 
list command into a file named Istfile. If 
you are using a multi-user system you can 
send the output of a command to another 
user with a command like: 

0S9: asm test. a 1 >/T2 

which would send the listing from the 
assembly of test. a to the device called 
/T2, which is usually a terminal, 

I redirect Standard Output more than 
the other paths, but there are reasons to 
redirect the other paths as well. The 
Standard Input path is the one which pro- 
grams usually read from. A program can be 
fed a canned script of commands by redi- 
recting its Standard Input to a disk file 
with the commands In it. I sometimes 
insert this command In my startup file: 

debug <startup. debug >/NL 

This runs the Microware debugger with its 
input coming from startup, debug, and its 
output going to a special SCF device which 
I made public In the first column I wrote 
(/NL is a null device -- 1t makes anything 
you send to it disappear). By putting 
debug in my startup file like this I can 
easily apply patches to resident modules 
evBry time I boot my system. 

The Standard Error path ls used so 
infrequently that it is easy to forget that 
it exists. It is the path which programs 
usually use for serious error messages. 
Usually, it Is a good idea to leave the 
Standard Error path directed to the screen. 
but sometimes It should be redirected. 
Some compilers send syntax errors, or at 
least summary statistics out the Standard 
Error path. If you want to run a program 
that uses the Standard Error path in back- 
ground while you edit In foreground, it is 
wise to redirect the both the Standard Out- 
put and the Standard Error paths of the 
compiler to disk files or the printer, oth- 
erwise you may find messages from the com- 
piler cropping up in the middle of your 
screen at awkward times. 
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Redirection almost always works fine, 
^>wt there are some problems lurking around. 
.1 shouldn't be the responsibility of a 
i<;er to watch out for these problems, but 
JS-9 is designed with the assumption that 
orograms will follow some conventions 
-applying to their use of the standard 
paths. Some programs rely on dealing with 
particular devices. These programs should 
open special paths to those devices, but 
some use the standard paths for device 
dependent 1/0. These programs should be 
avoided if possible. 

The typical OS-9 system comes with 
three types of files. Sequential Character 
Files, Random Block Files, and Pipes. 
Sequential Character Files (usually called 
SCF files) are written or read from begin- 
ning to end. The most common SCF files are 
Terminal input and output, printer output, 
and modem input and output. The bytes in a 
RBF file (files handled by the RBFMAN file 
manager) can be read in any order. Disk 
files and other files like them, such as 
files 1n bubble memory or main memory, are 
usually RBF files. There is only one type 
of Pipe file, that is a temporary file kept 
in main memory which is used a buffer 
between one program's output and another 
program's input. 

Unless a program concerns itself with 
timing issues or uses the more exotic 
GETSTAT/SETSTAT system service requests. 
there is no way for it to tell the differ- 
ence between one device and another provid- 
ed the devices are of the same type (RBF, 
SCF, or Pipe). Some programs can't have 
their standard I/O redirected to a RBF file 
or a Pipe, but the great majority can. If 
a program uses SCF-specifIc GETSTAT/SETSTAT 
codes it win only be possible to use it 
with ihe proper type of files, but all but 
one of the programs that I know of from 
Microware and other major vendors can have 
their I/O redirected without restriction. 
The one exception is Microware 'S Pascal 
with old versions of OS-9. All programs 
written in that language, including the 
compiler itself, try to rewind their stan- 
dard output file when it starts. The SCF 
file manager deals with this strange 
request correctly by Ignoring it, but the 
Pipe manager returns an error if anyone 
tries to rewind It. If you try to redirect 
the output of a program written in Pascal 
to a Pipe, the program will die as soon as 
it's started. Microware has a fix for this 
problem if you run Into it. 



CHANGING OS-9'S DEVICE SUPPORT 

The modular design of OS-9's I/O system 
allows new devices to be added and the sup- 
port of old devices to be enhanced with the 
only restrictions being the wishes and 
budget of the person responsible, and the 
memory constraints of the computer. Sup- 
port for 1/0 starts at the lOMAN module 
which fields each I/O system service 
request and sometimes does a little work 
before passing it off to the appropriate 
module. File managers including SCF and 
RBF are the next level down from lOMAN; 
they do most of the file handling work that 
Isn't specific to a particular piece of 
hardware. The device drivers, such as ACIA 
and PIA, handle the interface with the I/O 
hardware. The device descriptor modules 
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contain the directions which all these mod- 
ules follow. There is a descriptor for 
each device in an OS-9 system containing no 
executable instructions, but lots of data 
which controls the other I/O modules. 

Hardware that requires complicated new 
modules for the I/O system should come with 
the necessary modules. The hardware vendor 
has to have the modules written (or write 
them), but a customer need only load the 
modules -- normally by including them in 
his boot -- in order to add software sup- 
port for the device to his system. This 
sets 0S'-9 apart from many operating systems 
in which a major part of the operating sys- 
tem has to be changed for any new device. 

Hardware vendors often need to write 
1/0 modules in order to sell their products 
to the DS-9 community, but anyone can write 
I/O modules if the need or the mood takes 
them. Writing an entire new I/O subsystem 
would require a lot of work, but most prob- 
lems can be solved with much less effort. 
Many devices can be accommodated by OS-9 
without any serious programming at all by 
creating new device descriptors. Device 
descriptor modules specify how each device 
is to be treated. The device descriptor 
contains fields which indicate (to lOMAN) 
which file manager and device driver should 
be used for the device, an absolute physi- 
cal address for the device, and any other 
data specific to the particular device 

The first 18 bytes of all device 
descriptors have the same format. The 
first nine bytes are common to all module 
headers (Sync Bytes, Module size. Offset to 
Module Name, Type/Language ($F1), 
Attributes/Revision, and Header Parity 
check). Of these, the module attributes 
are most interesting in the context of the 
device descriptor. If the device descrip- 
tor module is marked reentrant, the device 
can be used by more than one process at a 
time; otherwise, it can only be linked to 
or opened by one process at a time. Device 
descriptors which are not reentrant are not 
only restricted to use by only one process 
at a time, they can't be linked to by debug 
at all if they are in the boot. Some 
devices, such as the printer, shouldn't be 
reentrant unless you feel very ready to be 
responsible. OS-9 will happily mix output 
from several programs line by line on the 
printer if you tell it to. 

The format of the next nine bytes is 
common to all device descriptors. The 
fields are; the offset to the File Manager 
name (e.g., RBF) for two bytes, the offset 
to the Device Driver name (e.g., ACIA) for 
two bytes , the mode (what the device can 
do, e.g. Read/Wr 1 te/execute) for one byte, 
the device controller's real address for 
three bytes, and the length of the Initial- 
ization table. 

After the first 18 bytes, different 
types of devices have different fields. 
The Initialization table which follows the 
byte with Its length contains most of the 
fields that are interesting to play with. 
After the ini t ial izat - c^ table there is 
nothing but module names and the CRC. 

There are eleven fie ds in the initial- 
ization table for RBF-type devices (disk 
drives). The first field is one byte long 



and contains a 1 indicating that this is a 
RBF device. The other fields are; 

drive number 



step rate 

device type 

media density (0=single, 1»doub1e) 

number of cylinders (two bytes long) 

number of surfaces, verify (O^verify 
writes) 

default sectors per track for two 
bytes 

default sectors per track on track 
zero for two bytes 

sector interleave factor 

segment allocation size 

The step rate can take on values of 0..3 
with the higher numbers reflecting higher 
stepping rates. 

In the device type byte three bits are 
significant. Bit zero indicates a 8" flop- 
py i f it is one. Bit six indicates a non- 
standard format is being used if it is one. 
Bit seven being one indicates that the 
device is a hard disk. 

In the media density byte two bits are 
significant. Bit zero = 1 indicates that 
the device can handle double density. Bit 
one ^ 1 indicates that the disk is capable 
of double track density (96 tpi ) . 

The fields in the device descriptor are 
interpreted by the device driver end the 
file manager. Changing a value in the 
device descriptor can't force the other 
modules to do something they weren't writ- 
ten to do. For example, it probably isn't 
possible to use the device driver which is 
designed for floppy disks to control a hard 
disk -- changing the device type byte won't 



change the capabilities of the device driv- 
er. It is the option of the person writing 
the device driver to ignore anything in the 
device descriptor he wants. This means 
that there is no guarantee that the options 
in the device descriptor will work. I have 
heard that the floppy disk driver on the 
color computer ignores many of the options. 
I'll confirm this when I get one. 

A different set of fields are in the 
initialization table for SCF devices. Most 
of these fields control the line-editing 
function of the SCF manager. These are the 
values that are temporarily set by TMODE. 
They can be set permanently by changing 
them in the device descriptor. 

The initialization table in the device 
descriptor is copied into the path descrip- 
tor when a path is opened. There it can be 
changed and read by GETSTAT/SETSTAT calls,* 
but the change applies only to that partic- 
ular path. Changes to the device descrip- 
tor become the default for all paths opened 
to that device. 

The easiest way to change the device 
descriptors is with debug. If, for exam- 
ple, you want to add a new terminal to your 
system which you don't have a device 
descriptor for, you can modify a similar 
descriptor with debug to fit your require- 
ment (probably changing only the controller 
address and module name), save the result 
with the save command, and verify it with 
the update option to fix its CRC . The 
resulting module can be loaded and used. 

A device descriptor can be modified 
even while the device it specifies is in 
use because the descriptor iqiself is sel- 
dom referenced. In fact, as far as I know, 
the device descriptor is only used when a 
path is opened to the device. 

The device descriptor is the control- 
ling part of the OS-9 I/O structure. There 
are several things that can be done with 
them that I haven't covered yet, but that 
will be material for other columns. 
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COLUMN TWELVE -- THE COCO 



I now have a Radio Shack Color Computer 
with OS-9. I had hoped that this column 
would be about my first experiences as a 
new CoCo/OS-9 Level One user, but I have 
only had a few hours to play with the new 
machine and this column is due. 

Even just a few hours with the CoCo 
version of OS-9 is enough to form some 
first impressions. First, that really is 
OS-9 in there. All the standard commands 
and utility programs are included. Even 
XMODE, which didn't come with my Level Two 
system, was on the CoCo OS-9 disk, I am 
impressed with the performance of the CoCo. 
I am used to a two megahertz GIMIX system, 
and the CoCo is distinctly slower than 
that; but, I bet Basic09 on a CoCo would 
give an IBM-PC running its version of Basic 
a good race . I hope I have a chance to do 
some benchmarks soon. 

For a user moving from Color Basic to 
OS-9 the change must be wonderful . but con- 
fusing. OS-9 brings out much of the power 
hidden in that little off-white box. It 
also demonstrates the limitations of the 
Color Computer. After this column I intend 
to concentrate on positive aspects of the 
CoCo, but right up front I have to say that 
my new CoCo is a sit-down lawnmower with 
the soul of a Grand Pre racer. I want to 
get my complaining out of the way early, so 
this column is elected. 

On the hardware side, I guess my com- 
plaints can be summarized as: this computer 
seems to have \OBen designed to sell for 
under a thousand dollars. It is really 
unfair for me to think that this computer 
should have DMA (Direct Memory Access) for 
its disk I/O and a chip to do Its serial 
I/O. By doing those tasks In software 
Radio Shack hurt OS-9's performance, but 
they also kept the cost of the computer 
down. 

Certainly, my main reaction to the 
Radio Shack version of OS-9 was pleasure, 
but that didn't keep me from finding a few 
things to complain about. In my last col- 
umn I hinted that the disk driver included 
with CoCo OS-9 doesn't adhere to OS-9 stan- 
dards. I didn't make a strong statement 
because I didn't know from personal experi- 
ence. I can tentatively confirm the infor- 
mation now -- the CCDisk disk driver 
doesn't seem to refer to the parameters set 
in the disk device descriptors. 

The documentation that came with OS-9 
was also a disappointment. I expected 
entirely new books explaining the trickier 
aspects of OS-9 so any fool could under- 
stand it. The manuals I got are just 
prettied-up versions of the Microware manu- 
als with some parts missing. The documen- 
tation seems to have been very quickly 
done. I checked out the section on device 
descriptors first thing; the manual 
includes a full description of the device 
descriptor with no indication that some 
parameters don't work on the CoCo. Most of 
the information from Microware's manuals 
about adapting OS-9 to a new system are 
missing from Radio Shack's OS-9 documenta- 
tion. 



My complaints may sound significant, 
but they are not. The hardware limitations 
of the Color Computer are no worse than one 
would expect in a low-cost computer. The 
limited disk driver is only waiting to be 
replaced by a more general one. If no one 
else writes one, I may do It myself. The 
documentation problem is an Invitation to 
people like me. If OS-9 on the CoCo con- 
tinues to be as big a success as it has 
been, books will appear about it in fairly 
short order. 



NOTES ON COMPUSERVE 

I spent over two hours reading through 
the messages in the new OS-9 SIG on Compu- 
Serve. That bulletin board is really pick- 
ing up! People are beginning to buy 
Basic09 for the CoCo and are having trouble 
installing It. Some messages went some- 
thing like: I installed Basic09 on my sys- 
tem and it doesn't work -- HELP. I can't 
imagine how anyone Is able to figure out 
what went wrong from that kind of com- 
plaint; I certainly couldn't. Several oth- 
er people gave more detailed descriptions 
of their troubles. It sounded to me like 
they were having troubles with directories. 

When you start OS-9 running it will 
find a directory called /DO/CMOS on your 
system disk. This Is the directory OS-9 
will always execute programs out of unless 
you explicitly direct it to another direc- 
tory. Specifically, If you give the com- 
mand 

BASIC09 

OS-9 will look for an executable file 
called BA$IC09 in the /DO/CMDS directory. 
If it finds the program, everything is 
fine; otherwise, DS-9 will search the 
default data directory (Initially /DO) for 
a file called BASIC09. If BASIC09 in found 
in the data directory it will be taken as a 
shell command file, and a shell will- be 
started up to execute the commands. If 
that file turns out to be full of the 
machine code for Ba5ic09. the shell will be 
understandably confused. If you copy 
Basic09 from its distribution disk to the 
root directory for your system disk (which 
is what the command: 

copy /Dl/basic09 Basic09 

will do) your shell will get wrapped around 
the axle in about the way I just described. 
The way to avoid that problem is to put 
Basic09 In your execution directory with a 
command 1 ike: 

copy /Dl/basic09 
/DD/CMDS/Basic09 

The system disk on my CoCo is very 
full. If I had any number of my own pro- 
grams on that disk It would overflow. When 
that happens it Is time to divide the files 
on that disk between two disks. One way to 
spl it things up is to put BasicOS and a few 
other programs that are frequently used 
with Bas1c09 on a disk by themselves, and 
replace the system disk with the special 
Basic09 disk when it Is time to use Basic. 
There is nothing wrong with the Idea, but 
there is a nice pitfall waiting here too. 
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Directories are files, and, to save time, 
OS-9 remembers where the files you are 
using are on disk. When you boot OS-9 it 
determines where the directory /DO/CMDS is 
and will look right there next time it 
needs to find a program. If you pull out 
the system disk and put in your special 
BasicOS disk, OS-9 will read the location 
on the BasicOS disk where the /DO/CMDS 
directory was on the system disk. In the 
best case you will get a meaningful error, 
but you may not. The way to get around 
this problem is to remember to change your 
execution (and perhaps your data) directory 
when you change the disk it is on. That 
i s : 

Take the system disk out 
Put the Basic09 disk in 
type CHX /DO/CMDS 

which will cause OS-9 to find the /DO/CMDS 
directory again. Of course, if you decide 
to call the execution directory on your 
Basic disk something other than CMOS, 
that's fine; just change the execution 
directory appropriately. For example: 

0S9: CHX /DO/BASIC .CMOS 

If you put BasicOS on a disk separate 
from many of your other programs you may 
find yourself unable to get at some impor- 
tant program while you are using Basic09. 
There are at least three ways to solve this 
problem . 

OS-9 lets you load programs into memory 
and keep them there. You don't want to 
load too many because main memory is a very 
limited resource, but sometimes it can 
prove very useful to have a program or two 
in memory. If you insert your Basic disk, 

oad /D0/CMDS/basicO9 (note that I speci- 
fied the full directory name Instead of 
r^-.nglng the execution directory -- either 
w.- will work, but this way I won't need to 
' *:r;ge the directory back), then remove the 
£'f-. c disk and put the system disk back in. 

ow BasicOS is in main memory. You can see 
£sasic09 in the output of the MDIR command, 
and the MFREE command wi 1 1 show that there 
is much less free memory in the system than 
there was before you loaded BasicOS. Now, 
if you type 

0S9: basic09 



0S9: LOAD copy 
0S9: LOAD list 

remove the system disk 
insert the basic disk 

0S9: CHX /DO/CMDS 

and perhaps change the data 
directory 

0S9: CHD /DO/BASIC. PROGS 

then start basic09 

089: BASIC09 

If, for one reason or another, neither 
of these tricks will serve, you can change 
the execution directory from within 
BasicOS. For example, starting from a time 
when Basic09 is running with the basic disk 
on drive /DO: 



Replace the basic disk 
the programs you need 



with the disk with 



B: chx /DO/CMDS 



or whatever 



do what needs to be done, then, before 
exiting from basic, replace the basic disk 
in the drive. 

The BasicOS CHX command only changes 
the execution directory within BasicOS and 
any programs that are run from it. When 
you exit from Basic09 the directories that 
were active before you started BasicOS will 
be active again. 



THANK YOU GIMIX 

Ever since the CoCo version of OS-9 was 
announced with a different disk format from 
all other versions of OS-9 the users of 
large OS-9 systems have been grumbling 
about the incompatibility of our disk for- 
mats and the CoCo format. GIMIX has 
released a new floppy disk driver for their 
systems that supports reading and (if you 
have a 40 track drive) writing disks in 
CoCo OS-9 format. I am very grateful, and 
I am sure I represent many other OS-9 users 
when I thank GIMIX for their efforts. 



you will find yourself in basic much faster 
than when it had to be loaded from disk. 
To get rid of the copy of Basic09 in main 
memory use the UNLINK command: 

0S9: UNLINK basic09 

If there is some small number of small 
programs you want to use from within 
Basic09 you can load them into memory while 
the system disk is mounted. For example: 



A HANDY SHORTCUT 

I always use 32K when I run Dynastar, 
and I almost always use 24K for the Micro- 
ware Assembler. I am seldom content to use 
the minimum memory requirement given in the 
module header for any program. I have mod- 
ified the module headers of several pro- 
grams so they will automatically request 
the amount of memory I usual ly request for 
them. Debug can be used to do this. The 
commands which will modify Dynastar (OS) to 
default to its maximum memory size (32K) 
instead of the minimum (8K) are: 
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load ds 
debug 
1 ds 
. .+b 



=7F 
-FF 
Q 



To point at the permanent storage size in 
the module header. 
The value of this byte is $20 



The change is made so quit debug 



Test ds to make certain the new default is working. 
I first made certain I could edit a large file, then 
invoked procs from within ds and noted that ds was 
using 12o pages. 



If you want to make the change permanent 
use the following sequence: 

0S9: save /DO/x ds 
0S9: verify U </DO/x 
>/DO/C21DS/ds2 

Check its attributes 

0S9: attr /D0/CMDS/ds2 

You Win find that the execute and public 



execute attributes are missing, so turn 
them on 

0S9: attr /D0/CMDS/ds2 e pw 
Save the old version 

0S9: rename /DO/CMDS/ds old,ds 
Install the new one 

0S9: rename /D0/CMDS/ds2 ds 
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COLUMN THIRTEEN 



BIG SYSTEM HARDWARE 

Gimix has offered CoCo owners an 
attractive deal. Gimix its value. Even 
with this roughly thousand dollar break in 
the price of a Gimix the upgrade is expen- 
sive, but, speaking as a person who has 
used a Gimix for many many hours, if you 
can find the money, take this opportunity. 
What makes it worth thousands of dollars to 
move from a CoCo to a SS50 system? The 
most important difference is that every- 
thing works right on the larger systems. 
Another is that the more expensive systems 
are faster. A two megahertz 6809 runs more 
than twice as fast as a CoCo in its normal 
mode. The DMA disk controller and other 
powerful I/O devices also make a noticable 
difference. 

The upgrade from a CoCo to a SS50 sys- 
tem isn't the end of the line. All the 
major SS50 systems that support OS-9 sup- 
port both OS-9 Level One and Level Two. 
The move to Level Two involves a new ver- 
sion of the OS-9 operating system, but no 
change in applications programs. All the 
modern SS50 systems I know of can be 
upgraded with little or no change to the 
hardware (the main requirement is memory 
management hardware). I imagine that OS-9 
Level Two might run with the 56K of memory 
that Level One uses, but just barely. Lev- 
el Two begins to come into its own at 128K. 
At 344K, I have never run out of memory. 



BIG SYSTEM SOFTWARE 

There is a bit of controversy arising 
in the OS-9 world. Smoke Signal B^poadcast- 
ing has been responsible for a lot of 6809 
software over the years. There is even an 
operating system which they are responsible 
for. Now they are contributing to OS-9 
software. My understanding is that Smoke 
commissioned someone to work on the version 
of 05-9 licensed to them. Their consultant 
made OS-9 less modular in order to Improve 
its performance. The Smoke users I know 
confirm that the revisions make the Smoke 
version of 05-9 run faster than it used to. 
Running faster would seem to be an advan- 
tage, but the changes Smoke has made turn 
out to be a mixed blessing. There appear 
to be subtle incompatibilities between OS-9 
as it comes from Microware and OS-9 from 
Smoke Signal Broadcasting. I have spoken 
to Microware and they say that they can't 
support Smoke's version of OS-9 (that may 
have changed by the time you read this), I 
have had trouble exchanging software with 
Smoke users . 

The Smoke users are amazingly tolerant. 
I have read exchanges on the CompuServe 
OS-9 SIG in which Smoke users exchange tips 
on ways to prevent the DIR command from 
intermittently producing junk. 



This problem was resolved to everyone's 
satisfaction when Smoke agreed to offer 
their users a choice of modified or 
unmodified OS-9. 



I certainly approve of improving OS-9's 
performance, but it is very important that 
an ©Derating system be as standard as pos- 
sible. If I were buying a system from 
Smoke Signal Broadcasting, I would want 
strong assurances that their version of 
OS-9 was compatible with Microware's on 
every level. A good test would be that all 
applications programs and system modules 
that run under standard OS-9 should run 
under the modified one, and vice versa. 



THE COMPUSERVE OS-9 SIG 

The OS-9 special Interest Group on Com- 
puServe is booming, Messages flow through 
the bulletin board so fast I am beginning 
to question my ability to read them all. 
Many experienced OS-9 users regularly check 
in, but it is a particularly good resource 
for newcomers. I strongly suggest that yoU 
join CompuServe if there is an access point 
close to you. It is worth it even if you 
only use it to access the OS-9 SIG. 



OS-9 ON THE COLOR COMPUTER 

I have been saying nasty things about 
Tandy which aren't true. I blamed the 
sloppy programming in the CCDISK device 
driver on Tandy when it seems the blame 
should fall on Microware and Microsoft. 
The bootstrap for the CoCo is in ROM. 
There is only one bootstrap ROM, designed 
by Microsoft for use with Color Disk Basic 
(I guess). Microware had to design the 
CoCo implementation of OS-9 so it could be 
loaded with that Bootstrap. The CoCo boot 
ROM reads 15 sectors off track 35 into a 
fixed location in memory. The 0S9Boot file 
had to fit into those 15 sectors. This 
memory constraint forced Microware to pay 
even more attention to writing compact code 
than they usually do. Since 6809 instruc- 
tions that do direct memory references take 
less memory than indexed instructions, 
Microware used them whenever they could. 
Since versatile device drivers take more 
memory than limited drivers, they wrote 
limited drivers. Tandy. I apologize for 
the nasty thoughts I sent your way. 

I decided to write this month's project 
for the CoCo. I noticed that Color Basic 
has a number of commands which make assort- 
ed honks and beeps emerge from my TV. 
Basic09 has no way to make those noises, I 
Checked the "Color Computer Technical Ref- 
erence Manual" for information about the 
sound generator, and found that the Color 
Computer generates sound with a Digital to 
Analog converter. The output from the D/A 
converter is routed through an analog mul- 
tiplexer to the modulator, and hence to the 
TV. It looked like OS-9 could learn to 
make noise. 

I expect that the reason Microware 
didn't include sound generation in their 
OS-9 for the Color Computer is that sound 
generation with an D/A converter is a very 
time dependent operation. A note is played 
by gradually (in computer terms) raising 
and lowering the voltage generated by the 
D/A converter. This has to be done with a 
timing loop in a program. The timing loop 
must have exclusive use of the computer, or 
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the rate at which the voltage rises and 
^^alls will vary causing the note being gen- 
crated to rise and fall. Some people might 
find the resulting yodel surprising. A 
program can give itself exclusive use of 
the computer by masking out interrupts, but 
locking out interrupts for more than a few 
millionths of a second is antisocial behav- 
ior for any program -- even a part of the 
operating system. 

Still, the ability to at least be able 
to generate a beep seems important to me. 
I started by writing a program called Sound 
to investigate sound production. The pro- 
gram generates a saw-tooth wave that sounds 
rather like a saber saw cutting thin ply- 
wood, but It works. The most important 
discoveries I made while writing Sound were 
how to initialize the multiplexer so the 
D/A converter's output would be routed to 
the TV. The control registers at $FF03 and 
$FF23 both need to be modified. The fact 
that they could be modified was another 
interesting discovery. I am used to con- 
trol registers being either readable or 
writeable. These registers are to some 
extent read/write. CoCo programmers may 
take this for granted, but I was pleasantly 
surpr 1 sed . 

Once the control registers are set, 
sound can be generated by simply writing 
different values into the most significant 
6 bits of the byte at $FF20. The faster 
the value is changed the higher the pitch. 
I wrote the program to send 1000 waves, 
then stop- 

Tnere is lots of room for improvement 
in Sound. The quality of the note created 
by the program could be improved, and the 
program might even be made to play a song. 
I decided to drop Sound and work on build- 
ing e Device Driver for the D/A converter. 

The Device descriptor I wrote for the 
D/A converter. Beep, is almost as small as 
a Device Descriptor can be. The D/A con- 
verter is not a random access device so I 
decide to use the SCF file manager to drive 
it. There are no options except the one 
byte which indicates that it is a SCF 
device. There are three addresses in the 
descriptor. Normally a descriptor only 
needs one port address, but in this case, 
since the three addresses used in making 
the D/A converter make sound aren't relat- 
ed, I included all the addresses explicit- 
ly. 

The Device Driver, called Beeper, is 
not interrupt driven. Most OS-9 device 
drivers use interrupts to give them a way 
to avoid wait loops, but I couldn't find a 
way to get the D/A converter to generate 
interrupts. In this case Interrupts wer- 
en't necessary; the device responds as fast 
as data can be pumped Into it. 

The initialization entry puts some val- 
ues tnat will be needed In the termination 
routine into device static storage, and 
sets the two PI A registers that need to be 
adjusted to permit sound to be made. The 
termination entry sets the two control reg- 
isters back the way they were before Beeper 
started, and the GetStat and PutStat 
entries don't do anything at all. The read 
and write entries deal with the fact that 
the D/A converter only uses the high-order 



six bits of the register it is accessed 
through. 



INSTALLATION OF BEEP/BEEPER 

Beep and Beeper have to be typed In and 
assembled. As usual, the USE statements 
between the IFP1 and ENDC don't come out In 
the assembly listing. You will have to 
include use statements for both 0S9DEFS and 
SCFDEFS for these programs. When you 
assemble the Beeper file it will generate a 
file in the execution directory called 
Beeper with both Beep and Beeper in it. 

To use beeper first load it with the 
OS-9 command 1 ine; 

0S9: load beeper 

then link beeper with the command line; 
0S9: link beeper 

Since beeper Is the second module In the 
file it will have a tendency to disappear 
if you don' t 1 ink it. 

As a first try you can get a low growl 
out of your computer by listing a file to 
/Beep, I used 

0S9: list beeper >/beep 

To get a more interesting sound out of 
the device you will need to feed it mean- 
ingful data. The BasicOS program called 
TestBeep generates a thousand bytes of sine 
wave. TestBeep is intenoed to be packed 
and run out of the execution directory. If 
it is run from source the BYE should be 
removed. It takes a long time to initialize 
the array, so be patient. The wave can be 
sent one byte at a time with a loop like: 

for I«l to 1000 

put y/sound,note(l) 
next I 

But OS-9 doesn't do very well at outputting 
a single character at a time. This program 
segment demonstrates that by generating a 
low. raspy note. To get a higher, smoother 
note I sent the entire thousand-byte array 
with one write. The quality of the tone 
still leaves a lot to be desired, but it's 
the best I could do quickly. 



APPLICATIONS FOR /BEEP 

I Imagine that the timbre of the tone 
generated by TestBeep could be improved by 
spending more time with the wave form: the 
rough sin wave I use Is pretty crude. Cer- 
tainly the pitch can be varied by changing 
the frequency of the wave. I discovered 
that TestBeep just as it stands is a useful 
demonstration of OS-9's multitasking behav- 
ior. I started TestBeep with the command 
1 ine: 

0S9: BASIC09 TestBeep^ 

if you have RUNB 

0S9: TestBeep&t 
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will work fine. This runs the program as a 
background task. When the noise started, I 
ran a variety of different programs and 
noticed the effect on the sound. 

If you want to generate a higher pitch 
than you can get out of Beeper, I suggest 
doing more work in the device driver. The 
approach I have in mind is to add a buffer 
in the device static storage for Beeper. 
When Beeper receives a request to write a 
zero value it will load the next 256 bytes 
written into the buffer. When the buffer 
isn't being loaded, each value written to 
Beep will indicate a number of times to 
send the buffer out the D/A . I believe 
that this approach will prove to be really 
useful, especially if there is a default 
wave loaded into the buffer by the INIT 



code. 



THE USERS GROUP 

I hope all the members of the OS-9 
Users group will have their disks by the 
time you read this. I am afraid that some 
of you will have received the wrong type of 
disk. I am responsible for this, We don't 
have any record of the type of disk (size 
and format) any of our early members use. 
Some of the people who have joined recently 
have included information about their disk, 
but in most cases I have had to guess. If 
you get a disk you can't deal with, write 
to the Users Group address, and we will try 
to get you a disk you can read. 



SOUND 
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00001 
00002 
00003 
00005 
00006 
00007 
00008 
00009 
00010 
00011 
00012 
00013 
000 14 
00015 
00016 
00017 
00018 
00019 
00020 
00021 
00022 
00023 
00024 
00025 
00026 
00027 
00028 
00029 
00030 
00031 
00032 
00033 
00034 
00035 
00036 
00037 
00038 
00039 
00040 
00041 
00042 
00043 
00044 
00045 
00046 
00047 
00048 



0011 
0000 
0000 
0002 
0004 
0006 
0008 
0009 
OOOA 
00D2 
ODOD 
0012 



0012 
0015 
0017 
001 A 
OOIC 
OOIF 



0021 
0023 
0025 
0027 
0029 
002C 
002E 
0030 



0033 
0036 



0038 
0038 



TYPE 
87CD0065 

CNTL 

CNTL2 

PORT 

CNTR 

CNTLV 

CNTL2V 

DSIZE 

534F554E NAM 

ENTRY 
************* 

* Initialize addr 
* 

CCFF23 

DDOO 

CCFF20 

DDOA 

CCFF03 

DD02 

A6DA 

9708 

8A08 

A7DA 

A6D802 

9709 

84F7 

A7D802 

* Initialize the 

CC03E8 
DD06 

* Send waves 



nan 

ttl 

IFPl 

ENDC 

SET 

MOD 

RMB 

RMB 

RMB 

RMB 

RMB 

RMB 

RMB 

EQU 

FCS 

EQU 



Sound 

Sound generator for CoCo 



PRGRM+OBJCT 

ENDSND, NAM, TYPE,REENT-*-l, ENTRY, DSIZE 

2 Address of D/A control registe 

2 Address of another D/A control 

2 Address of D/A input 

2 Number of waves to send 

1 Initial value of first Control 

1 Initial value of other control 

200 STACK 

/SOUND/ 



esses in local storage 



LDD 
STD 
LDD 
STD 
LDD 
STD 



#$FF23 

CNTL 

#$FF20 

PORT 

#$FF03 

CNTL2 



Save initial va 
and set them to 



lues of control registers 
route D/A output to sound 



LDA 

STA 

ORA 

STA 

LDA 

STA 

ANDA 

STA 

counter 



[CNTL,U] 
CNTLV 
#$08 ^ 
ICNTL . U] , 
[CNTL2,U] 
CNTL2V 
#$FF-$08^ 
ICNTL2,U] 



LDD #1000 
STD CNTR 



8600 



L00P2 



LDA 



#0 
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000A9 




■ic**-k**ir 


j'r**- 


A 






00050 




* Send 


each wave 






00051 




* 










00052 


003A 






LOOPl 






00053 


003a 


A7D80A 






STA 


JPORT.U] 


0005A 


003D 


8B0A 






ADDA 


00055 


003F 


12 






NOP 




00056 


OOAO 


12 






NOP 




00057 


OOAl 


12 






NOP 




00058 


00A2 


12 






NOP 




00059 


00A3 


12 






NOP 




00060 


O0A4 


12 






NOP 




00061 


00A5 


12 






NOP 




00062 


0046 


12 






NOP 




00063 


00A7 


12 






NOP 




0006A 


00A8 


8100 






CMPA 


LOOPl 


00065 


OOAA 


26EE 






BNE 


00066 




*yf*yr5VA*A* 








00067 




* End 


of 


sending ( 
we still 


one wave. 


00068 




* See 


if ' 


need t 


send more 


00069 




* 










00070 


OOAC 


DC 06 






LDD 


CNTR 


00071 


OOAE 


830001 






SUBD 


CNTR 


00072 


0051 


DD06 






STD 


00073 


0053 


26E3 






BNE 


LOOP 2 


00074 




*i:itit****** 








00075 




* Rest 


ore 


initial 


values 


to control registers 


00076 




■h 










00077 


0055 


9608 






LDA 


CNTLV 
[CNTL,U] 


00078 


0057 


A7DA 






STA 


00079 


0059 


9609 






LDA 


CNTL2V , 
TCNTL2,U] 


00080 


005B 


A7D802 






STA 


00081 


005 E 


5F 






CLRB 


clear carry 
F$EXIT return to OS-9 


00082 


005F 


103F06 






0S9 


00083 


0062 


528D69 






EMOD 




0008A 


0065 






ENDSND 


EQU 


* 



00000 error (s) 

00000 warning (s) 
''065 00101 program bytes generated 
■'D2 00210 data bytes allocated 
ZF8 03832 bytes used for symbols 



BEEPER 
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00001 
00002 
00006 
00007 
00008 
00009 
00010 
00011 
00012 
00013 
000 14 
00015 
00016 
00017 
00018 
00019 
00020 
00021 
00022 
00023 
0002A 
00025 
00026 
00027 



OOFl 

0000 87CD0027 
OOOD 03 
OOOE FFFF20 

0011 01 
0012 

0012 00 
0001 

0013 FF23 
0015 FF03 
0017 A24545D0 
OOIB 5343C6 
OOIE A2454550 
0024 58AEA3 
0027 



TYPE 



OPTIONS 

OPTL 

CNTLl 

CNTL2 

BPNAM 

FMNAME 

DRVNAM 

BPEND 



NAM 

IFPl 

ENDC 

USE 

TTL 

NAM 

SET 

MOD 

FCB 

FCB 

FCB 
EQU 
FCB 
EQU 

FDB 

FDB 

FCS 

FCS 

FCS 

EMOD 

EQU 

TTL 



BEEPER 



BEEP Device Descriptor 

DEVICE DESCRIPTOR 

BEEP 

DEVIC+OBJCT 

BPEND , BPNAM , TYPE , REENT+ 1 , FMNAME , DRVNAM 

READ.+WRITE. MODES 

$FF,$FF,$20 PORT ADDRESS 



OPTL 

* 

DT.SCF 
*-0PTI0NS 

SFF23 

SFF03 

/BEEP/ 

/SCF/ 

/BEEPER/ 



Length of options section 



address of control byte 1 
address of control byte 2 
name of this module 
File Manager name 
Device driver name 



DEVICE DRIVER FOR D/A 
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00028 
00029 
00030 
00031 
00032 
00033 
00034 
00035 
00036 
00037 
00038 
00039 
OOOAO 
00041 
00042 
00043 
00044 
00045 
00046 
00047 
00048 
00049 
00050 
00051 
00052 
00053 
00054 
00055 
00056 
00057 

00058 
00059 
00060 
00061 
00062 
00063 
00064 
00065 
00066 
00067 
00068 
00069 
00070 
00071 
00072 
00073 
00074 
00075 
00076 
00077 
00078 



OOEl 
0081 
0000 
OOOD 
OOOE 
0014 



TYPE SET 

REVS SET 

87CD0076 MOD 

03 FCB 

42454550 BPRNAM PCS 

01 FCB 

Device Static storage 



DRIVR+OBJCT 

REENT+1 

BPREND , BPRNAM , T YPE , REVS , ENTER , MEMSIZE 

READ. + WRITE. DRIVER MODE 

/BEEPER/ 

1 EDITION 



D OOID 



ORG V.SCF 

'f Local part of static storage 

D OOID PORTA RMB 2 

D OOIF CTLIV RMB 1 

D 0020 CTL2V RMB 1 

D 0021 CTLIA RMB 2 

D 0023 CTL2A RMB 2 

D 0025 MEMSIZE EQU 

* Entry vectors 



System part of Static Storage 



PORT ADDRESS 
HOLD CNTLl VAL 
HOLD CNTL2 VALUE 
HOLD CNTLl ADDR 
HOLD CNTL2 ADDR 



0015 
W 0015 
W 0018 
W OOIB 
W OOIE 
W 0021 
W 002A 

0027 



16000F 
16002C 
160031 
16003E 
16003B 
16003A 



ENTER 



LBRA IN IT 

LBRA READ 

LBRA WRITE * 

LBRA GETSTAT 

LBRA PUTSTAT 

LBRA TERM 






INIT 



U ADDRESS OF DEVICE STATIC STORAGE 
Y ADDRESS OF DEVICE DESCRIPTOR MODULE 



0027 AEA813 
002A AFC821 
002D A68A 
002F A7C81F 
0032 8A08 
003A A78A 

0036 AEA815 
0039 AFC823 
003C A68A 
003E A7C820 
0041 8AF7 
0043 A784 

0045 5F 

0046 39 



LDX 
STX 
LDA 
STA 
ORA 
STA 

LDX 

STX 

LDA 

STA 

ANDA 

STA 

CLRB 
RTS 



CNTLl, Y 
CTLIA, U 

CTLIV, U 

#$08 

,X 

CNTL2 , Y 
CTL2A,U 

CTL2V,U 
#$FF-$08 



Get control address 1 out of D 
Save the address 

Get the present value of cntl 
save it for later restore 
set it for sound 



do the same stuff for cntl2 



CLEAR CARRY 
RETURN 
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00079 
00080 
00081 
00082 
00083 
00084 
00085 
00086 
00087 
00088 
00089 
00090 

00091 
00092 
00093 
00094 
00095 
00096 
00097 
00098 
00099 
00100 
00101 
00102 
00103 
00104 
00105 
00106 

00107 

o.-ns 

(■ -jy 

': Jill 

00112 
00113 
00114 
00115 
00116 
00117 
00118 
00119 
00120 
00121 
00122 
00123 
00124 



0047 READ 

* U ADDRESS OF DEVICE STATIC STORAGE 

* Y ADDRESS OF PATH DESCRIPTOR 
'^ RETURN CHARACTER READ IN A 



0047 AE41 
0049 A684 
004B 44 
004C 44 
004D 5F 
004E 39 



LDX 

LDA 

LSRA 

LSRA 

CLRB 

RTS 



V.PORT,U 



port address 
D/A value 



from device descr 



Shift out low order bits 
Clear carry 



004F 



k 



WRITE 



U DEVICE STATIC STORAGE 
Y PATH DESCRIPTOR 
A VALUE TO WRITE 



004F AE41 

0051 48 

0052 48 

0053 3402 
0055 A684 
0057 8403 
0059 AAEO 
005B A784 
005D 5F 
005E 39 



LDX 

LSLA 

LSLA 

PSHS 

LDA 

ANDA 

ORA 

STA 

CLRB 

RTS 



V.P0RT,U 



//•/iOOOOOOll 

,s+ 
,x 



Shift out high order bits 

save value to write 

Get current value at Port 

clear D/A value ^ 

put value to write in 

send it 

RETURN 



005F 
005F 
005F 5F 
0060 39 
0061 

^ U DEVICE STATIC STORAGE 



GETSTAT 
PUTSTAT 



TERM 



CLRB 
RTS 



0061 
0064 
0067 
0069 
006C 
006F 
0071 
0072 
0073 
0076 



AEC821 

A6C81F 

A784 

AEC823 

A6C820 

A784 

5F 

39 

A182B1 



BPREND 



LDX 
•LDA 
STA 
LDX 
LDA 
STA 
CLRB 
RTS 
EMOD 
EQU 



CTL1A,U 

CTL1V,U 

,X 

CTL2A,U 

CTL2V,U 

,X 



restore original Cntll value 
restore original Cntl2 value 
clear carry 



00000 error (s) 

00006 warning (s) 

$009D 00157 program bytes generated 

$0008 00008 data bytes allocated 

$164B 05707 bytes used for symbols 



TESTBEEP 

PROCEDURE TESTBEEP 

DIM NOTE (1000): BYTE 

DIM I: INTEGER 

DIM SOUND: INTEGER 

OPEN //SOUND *7BEEP*': WRITE 

FOR I«l TO 1000 

N0TE(I)«32*(1+SIN(I)) 

NEXT I 

FOR I-l TO 100 

PUT //SOUND, NOTE 

NEXT I 

BYE 
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WHERE NEXT? 



MORE ABOUT THE COCO DISK DRIVER 

After in sending last month's column I 
had second thoughts about what I said about 
the OS-9 disk driver for the CoCo. I 
didn't believe what I had written. The 
gist of what I said was that Microware and 
Microsoft together were to blame for the 
non-standard disk driver included with the 
CoCo OS-9. The boot ROM in the CoCo loads 
just 15 sectors from track 34 on the boot 
disk into set locations in memory and jumps 
to them. This is Microsoft's idea of a 
nice way to boot a computer. What I said 
last month was that Microware managed to 
squeeze all of OS-9 into those 15 sectors 
by extensive compression of the code. This 
sounded pretty extreme to me, but I thought 
that was what I had heard from Ken Kaplan 
out at Microware. 

Later. I became certain that I misun- 
derstood Ken. There is no way all the core 
resident parts of OS-9 could be squeezed 
into that amount of disk, and, if all of 
OS-9 was loaded by the ROM boot, why does 
the CoCo have a two stage boot? 

I called Microware to check my facts. 
I was wrong. In the first stage of the 
boot the CoCo ROM does load data from 15 
sectors on track 34 into memory and jump to 
it, but only a few important parts of OS-9 
are loaded: the kernal . the Init module. 
and the OS-9 bootstrap. These are the mod- 
ules that are found in ROM on other OS-9 
systems. The next stage of the boot uses 
the OS-9 bootstrap which was loaded in the 
first pass to do a normal OS-9 boot. The 
parts of OS-9 loaded in the first phase of 
the boot had to be squeezed hard, but much 
of the disk driver is loaded in the second 
phase of the boot . 



I have two very different OS-9 systems, 
a very large Gimix Level Two system and a 
CoCo. They fall at almost opposite 
extremes of the spectrum of microcomputers. 
The CoCo is so light and small that I think 
nothing of tucking it under my arm and 
walking a mile down to campus. The Gimix 
is so heavy that I am daunted by the 
thought of moving that stack of hardware 
even a few feet. The CoCo can't really 
handle more than one concurrent user. I 
routinely have two users on my Gimix and 
know people whose Gimix machines typically 
serve four or more concurrent users. The 
CoCo includes full graphics and a "termi- 
nal" protocol which is consistent across 
all CoCos . This is a big issue for other 
OS-9 users, particularly software develop- 
ers who have to write programs which can be 
configured for any terminal. 

Noting the similarities and differences 
between these computers has given me a lot 
of ideas about the kind of hardware I would 
like to see OS-9 running on. I imagine all 
computer users spend some time dreaming 
about the system they would have if only... 

My dream computer is a oersonal comput- 
er, or, to use the popular phrase, a per- 
sonal work station. I have grown used to 
the idea of OS-9 Level Two as a multi-user 
operating system, but I still prefer to 
think of it as a very powerful single-user 
system. Sharing computers is a way to save 
money. When I imagine the computer I would 
like, I don't consider money first. 

Naturally, my dream computer runs OS-9 
Level Two. It Includes a bit-mapped screen 
(color optional), several dedicated proces- 
sors, support for some graphics input 
device (I haven't chosen between a bit pad, 
a mouse and a light pen), and more than 
plenty of memory. 



There were a number of ways for Micro- 
ware to get a f ul 1 -featured disk driver 
into the CoCo, but they didn't. The 
restrictions on the first phase of the boot 
forced them to deviate from OS-9 standards 
in the boot module part of the disk driver. 
I believe they couldn't find a way to 
interest Tandy in the extra work (and memo- 
ry) required to discard the boot after its 
work was done and load a driver that worked 
independently. That is certainly reason- 
able. Why should Tandy be interested in 
making it easy for people to use non-Tandy 
peripherals? 

In any case, the problem seems to be 
solved. D. P. Johnson is advertising 
software that lets CoCo OS-9 deal with 
every disk format my Gimix can handle. I 
haven't tried his software, but I have 
heard from satisfied customers. I also own 
a 256K memory board made by Dan Johnson. I 
purchased one of the first boards he sold 
and had the kind of difficulties one might 
expect . I came to respect Dan Johnson 
while we struggled together to fix the 
problems which I discovered. He is good 
with hardware and software and VERY consci- 
entious. I can't recommend the software 
because I haven't tried it (yet). I do 
recommend the man who sells it. 



Many people seem to think that 128K is 
the right amount to run OS-9 Level Two in. 
Now you CAN run Level Two in even less, but 
you don't really appreciate it until you 
get to at least 192K. My dream machine 
would have at least 192K upgradable to 
256K, better still, 512K. There are so 
many uses for memory! Solid state disk 
drives or caches give better access times 
than hard disks but use a lot of memory. 
Complex programs can take lots of memory, 
but, when they are well written, they are 
powerful and easy to use. Sometimes lots 
of memory is needed for simple storage of 
data, I know a woman who keeps running out 
of space for her spread sheet on an IBM PC. 
She has about 600K! So lets put lots of 
memory in the dream machine. 

Graphics hardware is never good enough. 
At any rate that's the way I react to it. 
If the resolution and the number of colors 
is sufficient, the screen takes too long to 
update. If data is displayed by fussing 
with parameter lists and registers, the 
system is too limited. If the screen is 
bit-napped, it takes too much attention 
from the CPU to control the screen. The 
best solution seems to be to have a sepa- 



Of course, with that much RAM you need 

extra high-capacity disks to save what 
you're working on. 
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rate processor that deals with a bit-mapped 
display. If the graphics processor has a 
very high speed connection to the rest of 
the system, and can be dynamically pro- 
grammed to do more than just update the 
screen, the result should be speed and 
flexibility in graphics. 

There is use for more than one special 
processor in my dream compute*". If graph- 
ics support is included in the package, it 
would be foolish to require a terminal to 
be attached to the computer; an attached 
keyboard would be sufficient. A dedicated 
processor to scan the keyboard would take 
another load off the main processor. The 
other I/O devices could also use their own 
processors. My Gimix uses a 6809 on one of 
its serial cards to take some of the inter- 
rupt load off the main processor. It 
speeds my machine up a little, but doesn't 
have any other use. If the software for 
the I/O processor was loaded (and reloaded) 
by the main processor it would let the 
serial board be programmed to handle high- 
speed networks and other applications where 
timing is important. Even disk controllers 
could use their own special processors. I 
don't know of any programmable disk con- 
trollers they could do for disk I/O what 
smart seria cards has done for terminal 
I/O. The Gimix intelligent serial card con- 
tains a good part of SCFMAN. By unloading 
this work onto a special processor more 
cycles are left for user programs. RBFMAN 
is more complicated than SCFMAN and uses 
more CPU time. If most of that work could 
be done by a separate processor still more 
of the resources of the main processor 
would be available for the user. 

In fact, why talk about the main pro- 
cessor? In many cases OS-9 processes don't 
share memory with one another. If the 
dream computer had a bus where additional 
processor boards with some memory and per- 
haps I/O could be inserted. OS-9 could run 
independent processes on their own proce- 
dures. Most personal work station users 
don't need to run more than three or four 
processes at a time, so including many of 
what amounts to separate computers in the 
package would be wasteful. But, if the pow- 
er is available the applications will 
arrive . 

Mice are making a big splash these 
days. The Xerox Star, the Apple Macintosh 
and Lisa, and lots of more expensive work 
stations are using them. I would definite- 
ly pick a mouse over a joy stick. I have 
more trouble deciding that a light pen or 
graphics pad isn't a better tool than a 
mouse. The graphics pad is very precise 
and the stylus can be used about like a 
mouse. The arguments against graphics pads 
are that they are expensive, require desk 
space, and, for some applications, force 
the person using them to mentally map from 
the bit pad to the screen. The cost proo- 
lem I will ignore — after all this is a 
dream computer. The other two problems 
apply to mice as well. A light pen doesn't 
require desk space or a mental mapping, out 
I don't find them very precise and my hand 
obscures the screen when I am pointing. I 
Cftn't make up my mind. 

A fancy computer like this deserves 
fancy software. The peanut-butter and jel- 
ly programs now available for 05-9 just 
don't live up to the hardware. 
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My pet peeve with OS-S software has 
always been its lack of excellent editors. 
I like Dynastar fine, and I have heard nice 
things about Screditor and Stylograph, but 
these programs are at least five years 
behind the state-of-the-art. My dream 
machine deserves something special . Do you 
suppose EMACS could be ported to OS-9? 

A real database program would be nice. 
Something more than a filing cabinet or 
stack of index cards metaphor. 

I bet Knuth's TeX would run on some- 
thing like this. Some good graphics pro- 
grams, especially a graphics editor would 
make the graphics support a lot more use- 
ful . A real statistical program like SAS, 
or SPSS would make some people happy. Oth- 
ers need really good communications soft- 
ware . 

Languages aren't as important as the 
software written in them, but OS-9 is still 
painfully short of languages. I bet APL 
would run well under OS-9. Fortran is old 
fashion, but we really should have it. 
Those are the fundamental languages, but 
there is an endless list, including: Pilot, 
PL/1, Logo, Smalltalk, and others. 

Networking is another sexy topic these 
days. Expensive computers (which my dream 
machine is turning out to be) are generally 
used by people for whom communication is 
terribly important. Electronic mail, elec- 
tronic calendars, and sharing of files and 
other resources are important to them. 
OS-9 doesn't include networking software, 
but I think it will be at least as easy to 
run over a network as any other operating 
system. 

Enough of the dreaming. Truly, my 
dream machine is not so very far away. I/O 
processors exist, and I am sure more are 
coming. I have heard talk about slave pro- 
cessors. There are graphics boards avail ^ 
able for the SS-50 bus that are a lot like 
what I have in my dream machine. The CoCo 
comes with bit mapped graphics standard. 

For my Gimix I can hope for I/O and 
slave processors and a better (and less 
expensive) graphics board. For my CoCo I 
can aim low and hope for a disk controller 
with an onboard buffer, or aim high and 
look for a real Level Two system with as 
much done in hardware as possible (I/O, 
sound, and graphics). From my viewpoint as 
a Level Two user I think Tandy would be 
crazy not to offer a CoCo with Level Two. 
For a software person like me, it is fun to 
think up lots of things that hardware peo- 
ple should do for us, but the most impoi — 
tant part of any computer is its software. 

Some of my software wish list will have 
to wait for better hardware. In particular 
for more memory. Much of it can be done 
now. I have done some primitive networking 
myself. A really special database program 
or editor would push a 6809 hard, but might 
be possible. I have heard from people who 
are ucrking on lots of nice things for 
OS-9. Pretty near every piece of software 
for my dream machine is a project someone 
is working on now. 



MORE NOISE FROM THE COCO 



THIS MONTH'S DRIVER 



Last month I included a driver for the 
Digi tal -to-Analog converter in the CoCo . 
That driver was useful for low-speed D/A 
applications, but it didn't do \/ery well at 
sound generation. The highest pitch my 
driver could manage was something of a gur- 
gle. The speed problem wasn't 1n the driv- 
er. It takes a long time for a character 
to get through 5CFMAN. Even when a block 
of characters goes through together there 
IS enough delay in the transmission of each 
character to make smooth, high- frequency 
waves impossible. Fortunately, generating 
music isn't the only purpose for an D/A 
converter. Controlling lab instruments, 
motors, and such are all fine applications 
which only require a voltage to be changed 
infrequently -- 10 times per second at 
most . 

I ended last month's column with a few 
suggestions for ways to make the D/A driver 
better at generating sound. This month I 
went ahead and took my suggestions. This 
month's A/D driver does a pretty good job 
of making music. It even makes nice 
chords. I made the improvement I suggested 
last month. If the driver receives a zero, 
it places the next 360 bytes sent to it in 
a special buffer. Characters that don't go 
into the buffer cause the contents of the 
buffer to be transmitted through the D/A a 
number of times corresponding to the magni- 
tude of the character written. Since it 
takes a fixed amount of time to transmit 
the buffer, each character from $01 to $FF 
will take a fixed amount of time to send. 
This way each character sends a note of a 
set duration whatever the pitch. 

At first I used a buffer 128 byte^ 
long. That was easy to handle in BEEPER, 
but it was hard to build a wave in. It is 
important that a whole number of cycles fit 
into the buffer. It was difficult to gen- 
erate a wave that fit precisely into 128 
values. Numbers like 90 and 360 work bet- 
ter when angles are measured in degrees (if 
they are measured in radians it is hard to 
make any integers come out evenly.) I 
tried a 90 byte buffer, but I found it hard 
to store smooth, high-pitched tones in it. 
After the buffer got over 128 bytes long, I 
used the D register to offset the index 
into it so length didn't make much differ- 
ence. I chose 360 bytes as the length of 
the buffer because it is an easy number to 
work with when generating the wave. 

Interrupts are a problem to time- 
dependent things like music. I tried 
BEEPER with interrupts masked and unmasked. 
When interrupts are unmasked the sound is 
definitely not pure; however, when the 
interrupts are masked lots of bad things 
happen. With Interrupts masked nothing 
happens except operation of the D/A. Time 
doesn't get updated, the keyboard doesn't 
get scanned, and. if you are using the 
RS-232 port, it comes to a halt. In the 
version of BEEPER included with this column 
I commented out the ORCC and ANDCC . Try it 
both ways and choose for yourself. 



I got a little carried away with the 
test driver for BEEPER. The program calls 
for a magnitude and frequency for a wave 
(the numbers are only relative). The sine 
wave generated with these numbers is added 
to whatever wave has already been generat- 
ed. The resulting wave is displayed. If a 
Y is entered, the wave is loaded into BEEP- 
ER'S buffer and a few beeps are sent, if an 
A is entered another sine wave is prompted 
for and added to the existing wave, and if 
anything else is entered the wave is erased 
and the program starts over with a clean 
slate . 

I am afraid that this test driver is 
another program that needs work. BEEPER 
truncates numbers greater than 63 to 63. 
If the sum of the sine waves loaded into 
BEEPER'S buffer is greater than 63 at any 
point the wave wi I'l be clipped (as hi-fi 
people say). It would be good if TBEEP2 
would check for this. I also get pretty 
frustrated when I don't like the last sine 
wave I added to a wave I am building and 
have to wipe out the entire waveform to get 
rid of 1t. On the other hand I am rather 
partial to the graphic display of the wave- 
form. 



THE USERS GROUP 

Things aren't moving as quickly for the 
OS-9 Users Group as we hoped they would. 
We published our first news letter (called 
MOTD) months ago. By the way, if you are a 
member and didn't receive a copy of MOTD. 
send a note to the Users Group. Our system 
for keeping track of members seems pretty 
reliable, but it may have cracks in it. We 
are working on the second issue. The most 
important thing to most members seems to be 
the software exchange. There have been a 
number of problems getting the software 
exchange disks out. The most interesting 
problem has been a disk incompatibility 
between 40 track disks written by 80 track 
drives on two different manufacturer's sys- 
tems. Watch for this probleml 

There also seems to be some trouble 
getting disks. Three dollars per disk 
delivered to a member is a very low price. 
It's hard to be too impatient. In any 
case, barring another serious hold-up, the 
disks should be in the mail by late March. 
Let me say again that we don't know the 
disk format many users need. If I guess 
wrong, send the Users Group a letter and 
we'll try to find a way to straighten 
things out. 
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ODOOl 








NAM 


BEEPER 


00002 








IFPl 


Use 0S9DEFS, SCFDEFS and lODEF 


OOOOA 








ENDC 


and ENDC 


00005 








USE 


BEEP 


00006 








TTL 


DEVICE DESCRIPTOR 


00007 








NAM 


BEEP 


00008 


OOFl 




TYPE 


SET 


DEVIC+OBJCT 


00009 


0000 


87CD0027 




MOD 


BPEND, BPNAM , TYPE . REENT+ 1 , FMNAME , DRVNAM 


00010 


OOOD 


03 




FCB 


READ.+WRITE. MODES 


00011 


OOOE 


FFFF20 




FCB 


$FF,$FF,$20 PORT ADDRESS 


00012 












00013 


0011 


01 




FCB 


OPTL Length of options section 


00014 


0012 




OPTIONS 


EQU 


* o r- 


00015 


0012 


00 




FCB 


DT.SCF 


00016 


0001 




OPTL 


EQU 


^-OPTIONS 


00017 












00018 


0013 


FF23 


CNTLl 


FDB 


$FF23 address of control byte 1 


00019 


0015 


FF03 


CNTL2 


FDB 


$FF03 address of control byte 2 


00020 


0017 


A2A5A5D0 


BPNAM 


FCS 


/BEEP/ name of this module 


00021 


OOIB 


53A3C6 


FMNAME 


FCS 


/SCF/ File Manager name 


00022 


OOIE 


A2A5A550 


DRVNAM 


FCS 


/BEEPER/ Device driver name 


00023 


0024 


58AEA3 




EMOD 




0002A 


0027 




BPEND 


EQU 


* 


00025 








TTL 


DEVICE DRIVER FOR D/A 
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00026 
00027 
00028 
10029 
;.0030 
;D031 

•'J032 
VJ033 
C0034 
:0035 

')036 
337 
038 

.039 

.040 
.0041 
30042 
0OO43 
00044 
00045 

00046 W 

00047 W 

00048 W 
00049 
00050 
00051 
00052 
00053 
00054 
00055 
00056 
00057 
00058 
00059 
00060 
00061 
00062 
00063 
00064 
00065 
00066 
00067 
0Q068 

569 
570 

00071 

00072 

00073 



OOEl 
0081 
0000 
OOID 
OOID 
OOIF 
0020 
0021 
0023 
0025 
0168 
0027 
018F 
OOOD 
OOOE 
0014 



87CD00D8 



TYPE 
REVS 



PORTA 

CTLIV 

CTL2V 

CTLIA 

CTL2A 

COFFSET 

BUFLEN 

BUFFER 

MEMSIZE 

BPRNAM 



03 

42454550 

01 
*********** 

* Entry points 



SET 
SET 
MOD 
ORG 
RMB 
RMB 
RMB 
RMB 
RMB 
RMB 
EQU 
RMB 
EQU 
FCB 
FCS 
FCB 



DRIVR+OBJCT 

REENT+1 

BPREND , BPRNAM, TYPE , REVS , ENTER , MEMS IZE 

V.SCF 

PORT ADDRESS 

HOLD CNTLl VAL 

HOLD CNTL2 VALUE 

HOLD CNTLl ADDR 

HOLD CNTL2 ADDR 

OFFSET IN BUFFER 



2 

1 

1 

2 

2 

2 

90*4 

BUFLEN 



READ.+WRITE. DRIVER MODE 
/BEEPER/ Program Name 
1 EDITION 



0015 
0015 
0018 
OOIB 
OOIE 
0021 
0024 
0027 



16000F 
160042 
160047 
1600A0 
16009D 
16009C 

******* 

* U ADDRESS 

* Y ADDRESS 



ENTER 



INIT 



LBRA INIT 

LBRA READ 

LBRA WRITE 

LBRA GETSTAT 

LBRA PUTS TAT 

LBRA TERM 



OF DEVICE STATIC STORAGE 
OF DEVICE DESCRIPTOR MODULE 



0027 
002A 
002D 
002F 
0032 
0034 
0036 
0039 
003C 
003E 
0041 
0043 
0045 
0047 
0048 
004B 
004E 



AEA813 

AFC821 

A684 

A7C81F 

8A08 

A784 

AEA815 

AFC823 

A684 

A7C820 

84F7 

A784 

8D08 

5F 

E7C825 

E7C826 

39 



LDX 


CNTLl, Y 


STX 


CTL1A,U 


LDA 

STA 


CTLIV, U 


ORA 


#$08 


STA 


,x 


LDX 


CNTL2,Y 


STX 


CTL2A,U 


LDA 


,x 


STA 


CTL2V,U 


ANDA 


#$FF-$08 


STA 


,x 


BSR 


INITBUF 


CLRB 




STB 


COFFSET, U 


STB 


COFFSET+1, 


RTS 





Move the address of cntll byte 
from the D. Descriptor to stati 
save the value of the cntll by 

set one of the bits 

that turns on sound 

Move the address of cntl2 byte 

from the D.Desc to static slor 

save the value of the cntl2 by 

set the other bit 

that turns on sound 

Initialize the sound buffer 

CLEAR CARRY 

Coffset is a two byte field 

RETURN 



U 
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00074 

00075 

00076 

00077 

00078 

00079 

00080 

00081 

00082 

00083 

00084 

00085 

00086 

00087 

00088 

00089 

00090 

00091 

00092 

00093 

00094 

00095 

00096 

00097 

00098 

00099 

00100 

00101 

00102 

00103 

00104 

00105 

00106 

00107 

00108 

00109 

00110 

00111 

00112 

00113 

00114 

00115 

00116 

00117 

00118 

00119 

00120 

00121 

00122 

00123 

00124 

00125 

00126 

00127 

00128 

00129 

00130 

00131 

00132 

00133 

00134 

00135 

00136 

00137 

00138 

00139 

00140 

00141 

00142 

00143 

00144 

00145 

00146 

00147 

00148 

00149 



* Put something that won't sound too bad 



OOAF 
OOAF 
0052 
0055 
0055 
0057 
005A 
005C 
005D 



005D 
005F 
0061 
0062 
0063 
006A 
0065 



0065 
0068 
006A 
006D 
006F 
0070 



0072 
0075 

0077 
0077 
007A 
007C 
007C 
007E 



0080 
0082 
0084 
0086 
0088 
008A 
008C 

008E 
0090 
0093 
0095 
0097 
0099 
009B 

009D 
009F 
OOAO 



into the sound buffer 

INITBUF 



30C827 LEAX BUFFER, U 

CC0167 LDD #BUFLEN-1 

INITLOOP 

E78B STB D.X 

830001 SUBD #i 

2CF9 BGE INITLOOP 

39 RTS 

READ 

* U ADDRESS OF DEVICE STATIC STORAGE 

* Y ADDRESS OF PATH DESCRIPTOR 
^ RETURN CHARACTER READ IN A 



AE41 

A684 

AA 

AA 

5F 

39 



LDX 

LDA 

LSRA 

LSRA 

CLRB 

RTS 



V.PORT,U 



get the value in the D/A regis 

Shift out the low order bytes 
Clear carry 



C0FFSET+1,U 
DEFINE 
COFFSET,U 
DEFINE 

SDEFINE 



WRITE 

* U DEVICE STATIC STORAGE 

* y PATH DESCRIPTOR 

* A VALUE TO WRITE 

6DC826 TST 

263F BNE 

6DC825 TST 

263A BNE 

AD TST A 

272F BEQ 

* LOOP THROUGH BUFFER 

30C827 LEAX BUFFER, U 

3A02 PSHS A 

* ORCC //INTMASKS Shut off interrupts 

CYCLE 

CC0167 LDD #BUFLEN-1 

3A06 PSHS D 

WLOOP 

LDA D,X 

PSHS X 

on second thought it would have 



If coffset isn*t zero 
we are in the process of filli 
buffer. We have to tst both C 

If the character to write is 
the sound buffer 



the address of the sound buffe 
SAVE COUNT 



Offset in buffer 
Save offset 

get a byte out of buffer 



A68B 

3A10 

**** on second thought it would have been 

**** better to just do a leax BUFFER, U later instead 



**** of saving this value here 



AEAl " LDX 

3A02 PSHS 

A68A LDA 

8A03 ANDA 

AAEO ORA 

A78A STA 

3510 PULS 
**^^* see note 

ECEA LDD 

830001 SUBD 

EDEA STD 

2CE5 BGE 

3262 LEAS 

6AEA DEC 

26DA BNE 
* ANDCC #$FF-INTMASKS 

3261 LEAS 

5F CLRB 

39 RTS 



OOAl 

OOAl ceo 168 
OOAA EDC825 
00A7 5F 
00A8 39 



SDEFINE 



LDD 
STD 
CLRB 
RTS 



V.P0RT,U 

A 

// 7.00000011 

,x 

X 

WLOOP 

CYCLE 

1,S 



#BUFLEN 
COFFSET, U 



The address of the D/A registe 
Build the byte to store in the 
register 



Store the new D/A value 
recover the buffer address 

§et the new offset in buffer 
ecriment the offset 

if it isn't negative send the 
Clear stack 

decriment repeat count 
cycle if not zero 

CLEAR STACK 



CLEAR CARRY 
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00150 
00151 
00152 
00153 
00154 
00155 
00156 
00157 
00158 
00159 
00160 
00161 
00162 
00163 
00164 
00165 
00166 
00167 
00168 
00169 
00170 
00171 
00172 
00173 
00174 
00175 
00176 
00177 
00178 
00179 
00180 
00181 
00182 
00183 

00000 
00003 
lOFF 
.CI 72 
il6D2 



* Load the Sound buffer 
* 



00A9 
00A9 
OOAA 
OOAB 
OOAD 
OOBO 
00B3 
00B6 
00B9 
COBB 
OOBD 
GOBF 
OOCO 
OOCl 
OOCl 
OOCl 
00C2 
00C3 



00C3 
00C6 
00C9 
OOCB 
OOCE 
OODl 
00D3 
00D4 
00D5 
00D8 



48 

48 

3402 

ECC825 

830001 

EDC825 

30C827 

308B 

3502 

A784 

5F 

39 



5F 
39 



DEFINE 



GETS TAT 
PUTSTAT 



LSLA 

LSLA 

PSHS 

LDD 

SUBD 

STD 

LEAX 

LEAX 

PUIS 

STA 

CLRB 

RTS 



CLRB 
RTS 



COFFSET.U 

n 

COFFSET.U 

BUFFER, U 

D,X 

A 

.X 



TERM 

* U DEVICE STATIC STORAGE 

AEC821 LDX 

A6C81F LDA 

A784 STA 

AEC823 LDX 

A6C820 LDA 

A78A STA 

5F CLRB 

39 RTS 

A60D8D EMOD 

BPREND EQU 



CTL1A,U 
CTL1V,U 

CTL2A,U 
CTL2V,U 



* 



error (s) 

warning (s) 

00255 program bytes generated 

00370 data bytes allocated 

058A2 bytes used for symbols 



Prepare the value 

save it 
Current offset 

Update offset 

location to store this byte at 
get the byte 
store it 



restore the original ctll valu 
restore the original ctl2 valu 



TBEEP2 

PROCEDURE 
0000 
0032 
0062 
008F 
00C7 
00F9 
OOFC 
013F 
0158 
015B 
0167 
0176 
0193 
01C4 
01E9 
0203 
020A 
021A 
022F 
02AA 
025B 
0266 
0271 
0272 
0275 
0286 
0289 
028B 
Q2B0 

oroo 

0£E3^ 
02^6- 



TBEEP2 
<^ 



TBeep2 is a test driver for the device driver 

BEEPER. It loads BEEPER with a wave form, 

then sends it a few more characters to test the tone. 

Note is an array which contains the values which will be sent to 
the D/A to form a note 



DIM NOTE (360) :BYTE 

DIM I, J, K: INTEGER 

DIM SOUND: INTEGER \(* Path number for A/D 

DIM MAGNITUDE, FREO: INTEGER \(- variables used to form the waveform 

DIM C:BYTE \(* a utility one-byte variable 

DIM CMD: STRING \{* waveform command 

OPEN #S0UND, "/BEEP": WRITE 
DEG \(* Use degrees for angles 
('^ Initialize Note to zeros 
FOR I«l TO 360 

NOTE (I) "0 
NEXT I 



('^^ Build waveform 



LOOP 



RUN GFX("ALPHA") \(* make screen printable 
K* Get parameters for a sin wave 
INPUT "MAGNITUDE^^ ".MAGNITUDE 
INPUT "FREQUENCY: ",FREQ 

(* add the sin wave to the wave in NOTE 
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0320 

0323 

033A 

0358 

0363 

0366 

037A 

037D 

038F 

039F 

03B0 

03BB 

03CD 

03CF 

03DA 

03E5 

03F7 

03F9 

OAOB 

040D 

0A2D 

0A38 

0A3B 

046A 

0A8F 

0A92 

0AA2 

0AB6 

OACl 

0AD3 

04D5 

OAEO 

OAEB 

OAFD 

04FF 

0511 

0513 

0533 

05 3E 

0541 

05 7A 
05A6 
05C1 
05CA 
05C9 
05D6 
05DA 
05E7 
0610 

06 34 
063F 
0641 
06 4E 
0652 
065F 
066B 
06AB 
06CB 
06E9 
06 FB 
06 FE 
0726 
0729 
073E 
0746 
0750 
0754 
0768 
0773 
0775 
0778 
0789 

078C 100 
0790 
07A1 
07AC 



(* 

FOR I-l TO 360 

NOTE (I) «N0TE (I) +MAGNITUDE* (1+SIN (I*FREQ) ) 

NEXT I 
(* 



f* 



Display the graph 



RUN GFX ("MODE", 0,1) 
FOR 1=1 TO 180 

J-NOTE(I*2)-2 

K-J+4 

IF J<0 THEN J=0 

ENDIF 

J=J*2 

K=K*2 

IF J>192 THEN J-192 

ENDIF 

IF K>192 THEN K-192 

ENDIF 

RUN GFX ("LINE", I, J, I, K) 
NEXT I 
(* 

(* Display a little bit of the next cycle 
(* to demonstate the the wave is continuous 
(* 
FOR 1-181 TO 255 

J-NOTE((-I-180)*2)-2 

K-J+4 

IF J<0 THEN J-0 

ENDIF 

J-J*2 

IF J>192 THEN J=192 
ENDIF 

IF K>192 THEN K-192 
ENDIF 

RUN GFX ("LINE", I, J, I, K) 
NEXT I 

(* There is no prompt because the screen is full of 
(* graphics, but enter Y<CR> A<CR>, or N<CR> after 
(* the graph has been dravm 

INPUT CMD 
EXITIF CMD«"Y" THEN 
ENDEXIT 

IF CMD<>"A" THEN 

FOR 1=1 TO 360 \(* The waveform is bad, 
NOTE(I)-0 \(* zero it and start over 
NEXT I 

ENDIF 

RUN GFX ("CLEAR") 
ENDLOOP 

RUN GFX ("ALPHA") 
RUN GFX ("QUIT") 

C»0 \('^ a zero tells the driver to use the next 360 characters 
PUT //SOUND, C \(* to build a new form 
PUT #SOUND,NOTE \(* send the new form 
PRINT "STARTING SOUND" 

(* Send a few beeps of different lengths 

FOR 1=100 TO 250 STEP 50 

C=I 

PUT #S0UND,C 

GOSUB 100 

PRINT "END OF LOOP ",I 
NEXT I 
END 

(* 

(* Delay a little 

(* 

FOR J»l TO 500 
NEXT J 

RETURN 
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COLUMN FIFTEEN 



THE OS- 9 SEMINAR 

I went to the OS-9 users seminar last sum- 
mer, so did almost every person I've heard 
of in the OS-9 community. It was interest- 
ing walking through the exhibit hall and 
listening to the speakers. The thing that 
makes me willing to go halfway across the 
country to take part 1n the seminar this 
summer is the fun I had last year talking 
with other OS-9 people. Most of us, myself 
included, spend our lives in a world where 
every other microcomputer user thinks the 
world ends right past PC-DOS and CPM. Last 
summer I fairly wallowed in the pleasure of 
being with hundreds of people who shared my 
interest in DS-9. We argued, agreed, com- 
plained^ puzzled. and applauded about 
things that are dear to OS-9 users (and not 
many others) . 

If you need a practical reason to spend 
a long weekend in Des Moines, bring a ques- 
tion with you. If you have been itching to 
show the person on the Microware hotline a 
problem that he can't reproduce, he'll be 
there. Go demonstrate the problem your- 
self. If you want to suggest that OS-9 
badly needs a WALL command you can probably 
find someone important and back him into a 
corner about i t . 

All the important vendors were there 
last year -- I assume they'll be back. If 
they come, you'll be able to check the 
Smoke Signal version of OS-9 for compati- 
bility with other versions. Try a few 
things on the GIMIX III. I hope Privac 
comes again; their graphics board is much 
more impressive in motion than in an adver- 
tisement. I imagine there'll be a bunch of 
new vendors there showing CoCo products. 

The vendors and Microware staff not- 
withstanding, the best place to .look for 
answers will be standing or sitting beside 
you (very likely at breakfast or some other 
improbable time). Last year I found the 
other users at the Seminar a mine of useful 
information. If you are a vendor, go to 
the Seminar even If you don't have a booth. 
It is a great place to test the water. 

The Seminar is a businesslike affair, 
but it is also something of a party: Jeanne 
Kaplan's party. Everyone who has dealt 
with Microware for any length of time knows 
that Jeanne is a consummate organizer. 
Last year everything ticked along smoothly 
despite the fact that she must have been 
slowed down a little by the child she was 
about to have. Last year Microware hosted 
a banquet and a fancy brunch. The Governor 
of Iowa came and gave us a little talk over 
dinner. Ken Kaplan handed out prizes to 
individuals who had made particularly dis- 
tinguished contributions to the OS-9 commu- 
nity. At the brunch mort prizes were hand- 
ed out. I wonder what is in store for us 
this year. 

Microware is going to give the Users 
Group some software for a raffle. I don't 
know just how it will be organized yet, but 



the plan is to hand the prizes out at the 
Sunday morning brunch. 

Last year we heard a lot about the new 
68000 version of OS-9. This year we may be 
able to see one in action. That's not 
official from Microware, but there are 
signs that it may be ready. 

I guess it sounds like I'm advertising 
the Seminar. I suppose I am. I wouldn't 
miss it for the world, and I hope I'll see 
you there. 



OFLEX 

Just today I received a copy of OF lex. 
This program runs Flex as a process in an 
OS-9 Level Two system. I'm afraid it's 
been too long since I used Flex with any 
regularity for me to give the program a* 
good workout. Still, I ran a few Flex pro- 
grams and checked out the interface to 
DS-9. 

I remembered from "The Soul of a New 
Machine" that Adventure was an important 
test used on new hardware. I have a ver- 
sion of Adventure which runs under Flex, so 
I ran through a dozen rooms or so with it 
and grabbed two or three treasures ... no 
problem. I compiled a Pascal program using 
the TSC Pascal compiler with no difficul- 
ties except some trouble remembering how to 
use Flex. 

Part of the OF lex package is a program 
called XCOPY that runs under OFlex. XCopy 
can copy from OS-9 files to Flex files and 
back. I tried every combination I could 
think of and couldn't make it fail. That 
brings up the one important failing I could 
find In OFlex; there is no FORMAT utility. 
I guess FORMAT is too near the hardware to 
run in what amounts to a virtual machine. 

OFlex can read and write Flex disks. 
It can also format files on an OS-9 disk so 
the files can be treated as Flex disks by 
OFlex. The files are accessed through a 
command called ASNDISK. Using ASNDISK. 
files can be associated with each disk num- 
ber (1 through 4). This is a useful fea- 
ture for Flex. I shudder to think of the 
problem it would be dealing with a hard 
disk full of Flex files. With OFlex the 
hard disk can be broken up into many small- 
er virtual disks giving manageable bunchs 
of files to work with. 

OFlex isn't reentrant. This is sad, 
but. as I remember it, many Flex programs 
change flags and pointers inside Flex. 
Because it isn't reentrant, each instance 
of OFlex running under OS-9 needs a full 
60K, but, if the memory is available, many 
users can run OFlex on the same machine. 
This could be viewed as an easy way of get- 
ting multi-user Flex. 

OFlex is licensed from TSC and Frank 
Hogg Labs. As far as I can tell it is reg- 
ular Flex with modified I/O which feeds 
into D5-9. It ran the programs I tried 
flawlessly, but I know of several Flex pro- 
grams (I've written some myself) which use 
memory-mapped I/O directly instead of going 
through Flex. They won't work under OFlex. 
Anyhow, If you have OS-9 and you wish you 
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erould run most of your old Flex programs, 
■r at least read the old disks. OFlex will 
:o what you need. If you have no particu- 
lar need for OS-9 but figure OFlex might be 
^]^ improved way to run Flex, you must be 
very brave. It is an improvement over reg- 
ular Flex in several ways, but one day a 
program you desperately want to run won't 
work with this mutation of Flex. In any 
case try OFlex with your software before 
you rely on it. 



ware C uses lots of internal subroutines 
and a special static storage location 
called flacc (floating point accumulator) 
to do floating point calculations. I had 
lots of trouble finding the floating point 
number and returning the number to the 
caller. As you can see from the programs, 
my solution was to use C to do everything 
in modf , and to find val and return a value 
in frexD. 



NEW MANUALS 

I got a stack of new 05-9 Manuals last 
week. I'm not an authority on most of the 
OS-9 Manuals, but I've practically memor- 
ized the System Programmer's Manual. The 
new manual 1S a big improvement over the 
old one. There is a section on memory man- 
agement for Level Two and a section on 
pipes with a few assembly language exam- 
ples. The Level Two Service Requests are 
in with the other requests, not isolated in 
an appendix. Speaking of Service Requests. 
the manual goes into a good deal more 
detail than it used to on some of them. 
The explanation of Chain takes more than 
two pages, Exit takes about a page and a 
quarter, as does Intercept. 

The new manual contains lots of useful 
snippets of code demonstrating tricky 
points. I was particularly pleased to see 
five chunks of about ten lines each that 
cover the most obscure parts of an inter- 
rupt driven device driver. I believe those 
chunks of code were taken straight out of 
the ACIA device driver. 

Microware has been producing steadily 
oetter manuals for the last two years. The 
new Systems manual is their best so far. 
.tf it had been available last January. I 
T, ight never have seen a need for this col- 



C FUNCTIONS 

I have been working on a program to 
model a problem in distributed systems for 
a course I am taking. I needed some func- 
tions to manipulate floating point numbers 
as a separate mantissa and exponent. I 
spent most of an evening fussing around 
witn assembler before I gave up and wrote 
the functions mostly in C. It was such a 
frustrating experience that I decided to 
include them in this column. I wrote frexp 
and modf to duplicate functions that are 
part of the UNIX math library. 

Frexp returns the mantissa of val as a 
double less than one. and stores the expo- 
nent in the integer pointed to by eptr. 
The exponent 1s for a power of two; that 
is, the number was (val =x*2**exp) . 

Modf separates a double Into an integer 
part and a fractional part. The integer 
part is stored at the address in ptr (as a 
double), and the fractional part is 
returned (also as a dout'e). 

I wrote most of the code for these 
functions In C because I couldn't do It in 
assembler. I certainly tried, but Micro- 



THE BUTTERFLY 

It looks like the Computer Science 
Department here at the University of 
Rochester is going to get a computer called 
a Butterfly. It Is named after the network 
used to connect its processors together. 
The Butterfly that will be coming here has 
128 68000 microprocessors. Each 6800C has 
at least 512K of memory and, potentially. 
Its own buss. They are all able to read and 
write one another's memory. I hear that 
this computer will have the fastest 
instruction rate in the world. Of course, 
instruction rates are an almost meaningless 
measure, but won't that be a marvelous com- 
puter to develope parallel algorithms on! 
•It's coming with a UNIX-like operating sys- 
tem, but I can't help but wonder whether it 
could run OS-9. 



DYNASPELL 

Last summer at the OS-9 Users Seminar I 
met Dale Puckett at dinner -- before we 
were both elected as Users Group officers. 
I had been a loyal user of Dynaspel 1 , a 
program written by Dale Puckett, but I 
wasn't entirely happy with it. In fact I 
had written a very mixed short review of It 
in this column. During dinner I made Dale 
sit through a careful explanation of my 
criticism of his program, and a long dis- 
cussion of what I thought a spelling check- 
er should do. 

Dale was very patient with me. He even 
encouraged me to go into more depth about 
my ideas for the perfect spelling checker. 
I told him that I would write a new, more 
complete review of Dynaspel! if he would 
send me a version that deserved fresh con- 
sideration. Some months later I got a 
package from Dale including something pret- 
ty close to my dream spelling checker. We 
went through some iterations working out 
various problems. Now I owe Dynaspel ^ a 
review. I have been very slow aoout writ- 
ing that review, so let me summarize here. 
I'll go Into more depth another month. 
Dynaspel 1 isn't perfect, but I haven't been 
able to find any bugs in the latest ver- 
sion. It is much faster than the early 
version I had. It Is able to look near 
misses up In its dictionary and suggest 
corrections when it suspects a spelling 
error . 

My remaining complaint about Dynaspel 1 
is that the new features don't go far 
enough. The "look up" feature isn't as 
selective as a would like. It often finds 
more possible spellings for a word than it 
can fit on the screen. On the other hand 
It sometimes doesn't search widely enough 
to find the correct spelling for me. I 
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also wish it would give me the features of 
a screen oriented text editor when it finds 
a spelling editor. Dynaspel 1 has a mode in 
which spelling errors can be viewed in con- 
text, but the context it shows is a screen- 
ful! of the document up to and including 
the word in error. I would like to be able 
to move forward and backward throught the 
document, and to change words other than 
the one in error. 



has required either slight of hand or very 
strange practices. Only modules running in 
the system address space can add Service 
Requests, but 05-9 doesn't include a way to 
run a process in the system address space. 
I have run device drivers and file managers 
just to add Service requests, and consid- 
ered renaming 0S9P2 as 0S9P21 and adding my 
own 0S9P2 which will link to and call 
059P21 . 



I used my early copy of Dynaspel! 
because I need a spelling checked badly and 
it was the best I had. I use it more often 
and more happily now. It is one of the 
best spelling checkers I know; mainframe 
programs included. 



A NICE EXPERIENCE 

Early last summer I bought a TeleVideo 
970 terminal. They were just becoming 
available on the market; in fact, I had a 
hard time finding one. It seems the boat 
bringing a large shipment in from overseas 
had sunk. I'm not certain I believe that, 
but it was definitely difficult to find one 
to buy. I finally found one, got it home, 
and started using it. Nice terminal. Big 
screen, nice keyboard. Almost too flexi- 
ble. 

After about a week I started finding 
bugs. A few commands didn't work right. I 
called the number in the manual and talked 
to an engineer. The next day I got a pack- 
age via Federal Express with new firmware 
ROMS. That wasn't the end of the problems 
with the terminal. I'm one of those annoy- 
ing people who reads the entire manual then 
tries all the strange combinations of com- 
mands just to see what they will do, and 
the 970 has a manual about two thirds of an 
inch thick. The last time I called them I 
told them that I needed a feature which was 
documented in the manual, but which the 
errata with the manual said was not imple- 
mented (downloadable fonts). Without a com- 
plaint they sent me a whole new logic board 
which supports that feature. 

I don't think I would recommend the 
TeleVideo terminal to most OS-9 users. The 
terminal costs over a thousand dollars. 
That makes it hard to justify when a ade- 
quate terminal only costs five or six hun- 
dred dollars. For those who take terminals 
seriously, it is worth what it costs. It 
supports ANSI standard and VT52 control 
sequences, and includes about every feature 
I can imagine except full graphics (they 
say that's coming). 

The best thing about the 970 is the 
excellent support TeleVideo gives. Many 
large vendors seem to lose interest after 
they sell you their product. TeleVideo has 
gone out of their way for me again and 
again. 



TRICKS FOR LEVEL TWO 

I just learned about 0S9P3 in the new 
OS-9 System Programmer's Manual. I have 
often wished for an easy way to add System 
Service Requests to OS-9. Under Level One, 
it isn't too hard, but under Level Two it 



Microware has included something like 
that last trick in Level Two. After 0S9P2 
is finished initializing (all it does is 
set up a list of Service Requests) it tries 
to find 0S9P3. There is no 0S9P3 unless 
the user adds it to the boot file, so it 
generally fails to find the module, but if 
it finds 0S9P3 it executes i t as a system 
module. This opens up lots of interesting 
possibi 1 i t ies . 

Other interesting possibilities are 
suggested by the SS.SIG and SS.Relea SetS- 
tat codes. SS.SIG instructs OS-9 to send a 
specified signal when data is ready from a 
path. The easy use for this is to wait for 
output from several paths at once. This is 
especially good for things like "modem" 
programs that need to wait for input from 
two paths simultaneously. Without this 
SetStat the only way to handle that problem 
was to poll both paths. 

It isn't difficult to write a program 
that polls a number of paths. In fact, 
polling is the way most of the more primi- 
tive microcomputer operating systems work. 
The problem with polling is that it wastes 
tremendous amounts of CPU power. I seldom 
type faster than 2 characters per second. 
If a program has to poll for my input it 
will look for something to read thousands 
of times before it gets anything. 

With SS.SIG it should be possible to do 
a couple of SetStats and wait for a signal . 
While an OS-9 program waits it uses essen- 
tially nothing but memory. This should 
make modem programs and other programs with 
similar problems much more efficient. 

The other use I can think of for SS.SIG 
is to solve the problem that devices can't 
be preempted. If you have a system with 
more than one terminal you have probably 
noticed that if you send a message to 
another terminal, the message waits until 
the user at the other terminal types a car- 
riage return. That's because there is a 
program (e.g. the shell) trying to read 
from that terminal. Until the read is fin- 
ished OS-9 won't allow any process to write 
to it. SS.SIG gives us a way to break that 
deadlock by not leaving a read active. 

I have included a trivial program which 
demonstrates the use of the SS.SIG setstat 
with this Column. It doesn't do anything 
useful -- just copies lines from standard 
input to standard output. The exciting 
thing is that it works! I ran tstssig on 
one terminal; typed a few lines into it to 
make certain that it worked; left it at its 
prompt, and went to my other terminal. I 
typed 

Echo Hi there >/terin 

on the other terminal and it appeared imme- 
diately on the terminal running tstssig-. I 
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went back to the termina) running tstssig on /term before the message was delivered 
and typed a blank. The blank caused a s^g- and the echo command completed, 
nal to be sent to tstssig letting It pro- 
ceed to the I$ReadLn. Once the read was 2 wonder whether the SS.SIG trick 
"up" /term was locked. I tried to send should be used as a matter of policy when 
another message to /term and found that I long waits for input are expected. 
had to wait until I typed a carriage return 
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TSTSSIG 



* 



Microware OS-9 Assembler 2.1 
tstssig - Test SSIG set stat 



00001 
00002 
00003 
OOOOA 
00005 
00006 
00007 
00008 
00009 
00010 
00011 
00012 
00013 
00015 

00016 0011 

00017 0081 

00018 0001 

00019 0000 

00020 OOOA 

00021 0064 

00022 00C8 

00023 0000 

00024 OOOD 

00025 OOIA 

00026 0015 

00027 0003 
00028 
00029 
00030 

00031 D 0000 

00032 D 0001 

00033 D 0065 
0003A D 012D 



0A/11/8A 21:58:57 



nam tstssig 

ttl Test SSIG set stat 



Page 001 



Test SS.SIG SetStat Service request. 
This program will copy lines from standard input 
to standard output without tying the device 
used for standard input up with a read, or using 
excessive amounts of CPU time by polling the 
standard input path. 

tstssig has no practical use that I can think of. 

use os9defs 



* 
* 
* 
* 
* 

* 



87CD0072 
5A737A73 
01 
3D3DBE 



Type 
Revs 
StdOut 
Stdin 
SSCode 
LineSiz 
Stacksiz set 
mod 
TstNam fcs 
Edition fcb 
Prompt fcs 
PromptL equ 



IFPl 

ENDC 

set 

set 

set 

set 

set 

set 



code used to indicate input wa 



Objct+Prgrm 

ReEnt+1 

1 



A 

100 

200 

TstLen, TstNam, Type, Revs , Entry, MemSire 

/Tstssig/ 

/">/ 
*-Prompt 



Static Storage 



* 



IntNo 
Line 

MemSize 



rmb 
rmb 
rmb 
equ 



1 

LineSiz 

Stacksiz 



Save the signal from the trap 
Storage for a line to echo 



00035 
00036 
00037 
00038 
00039 
OOOAO 
OOOAl 
000A2 
000A3 
0004A 
000A5 
000A6 
000A7 
000A8 
000A9 
00050 
00051 
00052 
00053 
0005 A 
00055 
00056 
00057 
00058 
00059 
00060 
00061 



0018 



Entry 
Set up signal intercept trap 



******** 



0018 
OOIC 
OOIF 
OOIF 
0023 
0027 
0029 
002C 
002E 
002E 
0030 
0032 
0035 
0037 
0037 
0039 
003D 
003F 
00A2 
OOAA 
0046 
00A9 
004B 



308D0050 
103F09 

308DFFF2 

108E0003 

8601 

103F8A 

2536 

8600 
C601 
103F8D 
2516 

3041 

108E0064 

8600 

103F8B 

2520 

8601 

103F8C 

2519 

20D2 



Loop 



StrtRead 



DoEcho 



leax 
0S9 

leax 

Idy 

Ida 

0S9 

bcs 

Ida 
Idb 
0S9 
bcs 

leax 

Idy 

Ida 

0S9 

bcs 

Ida 

0S9 

bcs 

bra 



Trap,PCR 
FSlcpt 

Prompt, PCR 

#PromptL 

#StdOut 

ISWrite 

Error 



Address of Interrupt trap code 




ady 
tt 
DoSSIG 

Line,U 

y/LineSiz 

#StdIn 

ISReadLn 

Error 

#StdOut 

ISWritLn 

Error 

Loop 



Write the prompt 



any data ready? 

No; wait for a signal 



Read a line 

and echo it back out 
Go prompt for the next line 



00062 
00063 
00064 
00065 
00066 
00067 
00068 
00069 
00070 
00071 
00072 



004D 
004D 
004F 
0052 
0055 
0058 
005B 
005D 
005 F 
0061 
0062 



C61A 

8E0004 

103F8E 

8E0000 

103F0A 

D600 

C104 

27CD 

43 

2000 



DoSSIG 



Idb 

Idx 

0S9 

Idx 

0S9 

Idb 

cmpb 

beq 

coma 

bra 



//SS.SSIG 

#SSCode 

iSSetStt 

#0 

FSSleep 

IntNo 

#SSCode 

StrtRead 



Error 



setstat function code 



Sleep until an interrupt comes 



set carry 
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Microware OS-9 Assembler 2.1 0A/11/8A 21:59:0A Page 002 

tstssig - Test SSIG set stat 



EOF isn't an error 



00073 


006A 


Error 






0007A 


0064 C1D3 




cmpb 


#E$Eof 


00075 


0066 2601 




bne 


Exit 


00076 


0068 5F 




clrb 




00077 


0069 


Exit 






00078 


0069 103F06 




0S9 


F$Exit 


00079 


*if****it*->\*i'<***i; 






00080 


* Trivial 


Interrupt trap 




00081 


jV 








00082 


006C 


Trap 






00083 


006C E7CA 




stb 


IntNo, 


0008A 


006E 3B 




rti 




00085 


006F 8AD34F 




emod 




0C086 


0072 


TstLen 


equ 


* 



save the interrupt code 



FREXP 



1 double 

2 frexp (val , iptr) 

3 double val; 
A int ^^iptr; 

6 register double *rp; 

7 int exp; 
8 

9 rg »= &(Val; 

10 /^^ at this point U contains the address of val */ 

11 //asm 

12 Idb 7,U get C exponent 

13 addb //128 

14 sex 

15 std ,S save exp 

16 Ida #128 

17 sta 7,U 

18 #endasm 
19 

20 *iptr = exp; 

21 return (val); 

22 I 



MODF 



1 /"^ modf returns the positive fractional part of val. 

2 and stores the integer part in the double pointed to 

3 . , by ptr. 

5 //define HAXLONG 13A217727 
6 

7 double 

8 modf (val ,ptr) 

9 double val, *ptr; 

11 { 

12 double tmp; 

13 

lA if(yal > MAXLONG) 

15 { 

16 *ptr - val: 

17 , return(O.O); 

18 } 
19 

20 tmp ^ (long) val; /^ truncate to int by coercion to long'*^/ 

21 *ptr * val - tmp; 

22 , return (tmp) ; 

23 } 
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STANDARDS 

Several months ago I mentioned Smoke's 
special version of 05-9 Level Two in this 
column. The questions I posed about its 
compatibility with Microware OS-9 stirred 
up a lot of commotion, but thanks to Don 
Williams' intervention no blood was shed. 
Smoke Signal has agreed to give customers a 
choice of the accelerated Smoke version of 
OS-9 or the Microware version. I think 
Smoke Signal deserves much credit for 
offering their customers this alternative. 
Some, perhaps most, people who use OS-9 
need extra speed enough to take the risk 
associated with a version of OS-9 not just 
like everyone else's. Cautious people 
(like me) can ask Smoke to send them the 
Microware version of OS-9. 

It" probably seems strange that I, a 
person who likes to fuss with operating 
systems, should get so worked up about 
Changes to OS-9. After all, I enjoy adding 
non-standard features to OS-9; I even pub- 
lish some of them in this column. 

Let me examine the question of stan- 
dards from a few points of view. There are 
things to be said for ignoring standards: 
mostly that ignoring existing standards is 
the way new. Improved ones are born. How- 
ever, consumers find standards convenient, 
and producers typically find standards cru- 
cial . 

Good examples of standards that beg to 
be ignored can be found In the busses 
invented in the early days of microcomput- 
ers. Engineers I know agree that the S-100 
bus is poorly designed. They would love to 
be able to make a few changes to its speci- 
fications. Our own SS-50 bus has gone 
through some evolution, but extending the 
address space beyond a megabyte will 
require further changes to the standard. 

I don't know hardware very well, but I 
imagine electrical engineers learn to work 
around standards about the same way pro- 
grammers do. Strict adherence to standards 
even when they have been outgrown often 
results in a "kludge." Either the old code 
is left there and a new structure built on 
top of it, or 1t is entirely replaced with 
code that does things "right," and adher- 
ence to the standard is added on as a spe- 
cial case, something ugly hanging off the 
side of the new idea. Both of these solu- 
tions look like poor design. 

IBM is a good example of a company, in 
fact an industry, caught on a horns of a 
standard. Years ago they Invented the 360 
architecture, a computer architecture that 
they used for all their computers. The 
idea of having a line of compatible comput- 
ers caught on nicely. Later, they extended 
the 360 architecture to include virtual 
memory and a few other goodies, giving the 
370 architecture. It was also quite suc- 
cessful . Customers seemed to appreciate 
being able to move to more powerful comput- 
ers without rewriting any software. Most 
recently, IBM produced XA, an extension of 
the 370 architecture which 370 customers 
can move to relatively painlessly. 



While these hardware changes were going 
on, operating systems were being improved. 
Programs that ran under MFT (an old operat- 
ing system for 360s) should run with no 
important changes under the latest version 
of MVS. This level of compatibility exists 
only because IBM has stuck grimly to its 
standards. This practice has brought them 
success, but not critical acclaim. I know 
operating system experts who pretend to 
feel sick when MVS is mentioned -- with 
some justification. That operating system 
contains layer after layer of history. In 
some places the complexity is so thick it 
is practically impossible to figure out 
what the programmer was trying to do. I 
imagine that, if the effort which goes into 
adapting MVS and 370 architecture to modern 
needs were directed toward designing new 
hardware and software, the result would be 
much faster and more useful than IBM's cur- 
rent 370-type products. I bet there arfe 
numerous engineers and computer scientists 
at IBM who yearn to junk the old standards 
in favor of something better. 

Standards like S-100, SS-50, and 
360/370 architecture have tied manufactur- 
ers to dinosaurs. They can't depart from 
their standards without hurting, and per- 
haps losing customers. The big computer 
and software manufacturers probably have 
mixed feeling about standards. The consum- 
ers of their products feel about the same 
way. 

It is hard to resist a sexy new comput- 
er or piece of software. The non-standard 
offerings are frequently faster and in var- 
ious ways better than the more conservative 
ones. The problem is that non-standard 
computers or operating systems are risky. 
The excitement of being the only person in 
the state with some fast, elegant operating 
system fades fast when you have troubles 
with software availability. 

We are lucky to be using hardware and 
software that have good standards. CoCo 
users are dealing with only one vendor and 
one machine. It is a shame Tandy didn't 
decide to use the same disk format all the 
other OS-9 systems do, but at least that 
problem is well known. It should be easy 
to exchange software and hardware between 
CoCos . 

The SS-50 bus is also a good standard 
which has been carefully respected by the 
vendors that support it. I ran my Gimix 
disk controller board with a SWTPc CPU 
board and memory boards from three differ- 
ent sources for about a year with no trou- 
ble. If all those manufacturers hadn't 
respected the SS-50 standard. I couldn't 
have done that . 

Microware OS-9 is solid across all the 
machines I know of. It is even possible to 
move from Level One to Level Two without 
changing software (provided the programs 
were written to appropriate standards). An 
OS-9 user can trade from a CoCo to a Helix 
to a Gimix III system without rewriting any 
programs except where they use special I/O 
features of each computer (like graphics on 
the CoCo). A software house can use their 
Gimix III system with its high speed and 
debugging facilities to develop software 
which will run on a CoCo. Usually we can 
order software without paying attention to 
the manufacturer of our machine. 
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The standards within OS-9 are as impor- 
ant as the interface to user programs. 
he device drivers and other system modules 
include with the column occasionally 
r.r.ould run on any OS-9 system with suitable 
hardware. I rely on Microware to stick 
with the interfaces between system modules 
that they have specified. If I ever find 
the money for it, I will be able to buy a 
graphics board for my system. If the ven- 
dor Is selling it for the OS-9 market, it 
will come with software to hook it into my 
system. That software will almost certain- 
ly work because its author wrote it and 
tested i t on a system with the same inter- 
faces between system modules as mine. 

Programmers have the most to gain from 
carefully followed standards. If someone 
buys a program that doesn't run on his com- 
puter, he will complain -- maybe return the 
program. This is a problem for the consum- 
er, but for the author of that program it 
is a disaster. Imagine what it would feel 
like to spend -thousands of hours creating a 
masterpiece of a program, then discover 
that it would only run on a few of the com- 
puters you had counted on for your market. 
With Microware OS-9 on any supported com- 
puter a programmer can be confident that 
that won't happen. 



It is a good question whether documen- 
tation for a project should be in the same 
directory with the source of programs for 
that project, in a sibling of that directo- 
ry dedicated to documentation for several 
projects (or just for a single project), or 
in a directory which is the child of the 
directory with the source in it. 

Some people think that directories 
should contain either only other directo- 
ries, or only data files. I don't think I 
like that idea, but I can see some value in 
it. 

Program names deserve serious thought. 
The shorter they are the faster they can be 
typed. It is easier to type L than LIST, 
but the shorter names are the more cryptic 
they become. LOOK or LOGOFF could also be 
abbreviated L. It has to be clear what the 
abbreviation stands for. It makes sense to 
me to give short names to frequently used 
programs. The names of the commands will 
stay fresh in the mind if they are fre- 
quently used even if they aren't ^/ery mne- 
monic. Less frequently used programs 
should have longer names both to save short 
names for more frequently used commands, 
and to jog the memory about their function. 



Programmers would like to see more 
standards in the DS-9 world. I have wished 
and worked for a standard terminal inter- 
face for a year now. It is a shame that 
each programmer who wants to sell his pro- 
grams has to invent a way to adapt his pro- 
gram to whatever kind of terminal it might 
encounter. A standard here would save days 
in program development time for each pro- 
gram that used it, encourage more program- 
mers to use terminal features supported by 
the standard, and give purchasers confi- 
dence that a program would work with their 
terminal s . 



STANDARDS THAT ARE THE USER'S 
RESPONSIBILITY 

If your system comes to you non- 
standard in some way, you should complain 
to the person responsible. Once you have 
it, it's your baby. You can generate addi- 
tional standards to simplify your system, 
or let chaos grow in your system. 



THE USERS GROUP 

The OS-9 Users Group plans to submit a 
list of "requirements" to Microware at the 
OS-9 Seminar this summer. If you have 
spotted a flaw in Microware' s software that 
you think is of general Interest, or would 
like to suggest that a new feature should 
be added to one of their products, this 
would be a good way to bring it to Micro- 
ware's attention. Submit your suggestion 
in writing to the Users Group early enough 
that it will reach us at least a few weeks 
before the Seminar. Please keep it to 
about a page or less. We will have copies 
of all the suggestions available at the 
Users Group booth at the seminar. The sug- 
gestions will be discussed at the Users 
Group meeting and those about which we can 
reach a consensus will be given to Micro- 
ware. We will try to get an official 
response to each suggestion from Microware 
-- something like: impossible, not inter- 
ested, will do, wonderful suggestion, or 
already done. 



Several areas come to mind as good 
places to institute standards. Directory 
structure is an especially good place to 
devise a standard. If you write a lot of 
programs, you may need a naming convention. 
A set of standards for documentation might 
help keep it up-to-date. 

There are two policies that can be used 
to guide the construction of directory 
structures. The directories can be 
arranged by what the contents are (pro- 
grams, text, spread sheet info.), or by 
what they are for (sort programs, house- 
hold, User Group files). Each method has 
its charm. I use both, each where it seems 
appropriate, but I wish I had decided early 
which way I wanted to go and stuck with it. 
Sometimes I have to search for minutes 
before I find a file I haven't used 1n a 
few months. 
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COLUMN SEVENTEEN — THE 
FIRST STEP INTO OS- 9 



There has been some call recently for 
information for the beginning user of OS-9. 
Color Computer users new to OS-9 feel 
swamped by the number of details involved 
in the operating system. This column is an 
attempt to make 05-9 seem simpler to new 
users . 

The OS-9 operating system has started 
to develop a reputation for complexity and 
obscurity -- in other words* user hostili- 
ty. It is an unjust accusation. The thing 
that makes OS-9 appear confusing is the way 
it is presented. There are many subtle 
features in the operating system, and a 
large array of utilities. The manuals that 
come with it could help but don't. The 
OS-9 manuals were written as reference man- 
uals, not tutorials. They drop everything 
on you at once. A new OS-9 user who is 
experienced with computers or very brave 
should read the manuals, wrap his mind 
around the whole thing, and sit down at the 
computer to enjoy OS-9. That is the quick, 
brute force, way to learn OS-9, but if it 
doesn't work for you, I recommend a gentler 
approach . 

My copy of CoCo OS-9 includes about 
fifty commands. All these commands are 
important to at least some people, but most 
of them are only confusing to to new OS-9 
users. The entire English language 
includes more than a hundred thousand 
words, but most people only use fewer than 
twenty thousand of them, and it is possible 
to communicate with a vocabulary of a thou- 
sand words or less. Operating systems like 
Unix and DS-9 are much like English in that 
respect. Of all the commands available 
under OS-9 about a dozen are really neces- 
sary. The bare minimum set of OS-9 com- 
mands are : 



backup 

copy 

del 

di r 

edit 

format 

free 

1 ist 

rename 

she! 1 

he shell is the program which processes 
he commands you type into OS-9 and runs 
he other commands. Several commands are 
built into the shell. They are: 

chd 

chx 



that you real ly 

chx. If you mean 

programming you 



• kill 

• setpr 

The only shell commands 
need to know are chd and 
to do assembly language 
will al so need : 

• asm 



• debug 

If you will be using Basic09 you will need: 

• Basic09 

• RunB 

GFX 

Of all these commands there are four 
that need explanation especially badly. 
Format needs to be discussed because it is 
dangerous; if it is used carelessly it can 
destroy important information. BACKUP is a 
relatively fast way to copy an entire disk 
(it is a good thing to get into the habit 
of doing this); perhaps a careful discus- 
sion of BACKUP will encourage people to use 
it more. Explaining DIR is a good excuse 
to say a few things about directories: an 
important feature of OS-9. CHX and CHD 
also relate to directories, and seem 
straightforward. What they are supposed to 
do matters less to a person with a OS-9 on 
a small computer than their unofficial side 
effects . 



FORMAT 

The format command is the first one to use. 
Until a disk has been formatted it Is unu- 
sable to OS-9. The format command writes a 
pattern on the disk which marks the disk 
off Into sectors (which amount to pigeon- 
holes for OS-9 to store data in). After 
writing the pattern format checks the disk 
to make certain the pattern is recorded 
correctly on the disk. If it isn't, format 
will note that the sectors where the errors 
occurred are faulty, and those sectors 
won't be used to store data. Format also 
writes some Information which will be used 
to manage files on that disk. In the pro- 
cess of doing all this the format program 
completely erases the disk. If the disk is 
fresh out of a box of new disks you can 
feel certain that there is nothing on the 
disk that you care about, but, if it Is one 
you are recycling, be careful. After for- 
mat is started any data that was on that 
disk Is gone forever. 

Put the disk you want to format in the 
drive you aren't using for the system disk 
(I'm going to assume you have your system 
disk in the drive DS-9 calls /DO, and the 
disk you want to format in drive /D1). 
Invoke the format command by typing FORMAT 
/D1 at the OS-9 prompt. The command line 
should look like: 

0S9: FORMAT /Dl 
to which you should get the response: 
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COLOR COMPUTER FORMATTER 

FORMATTING DRIVE /Dl 
Y (YES) OR N (NO) 
READY? 

This is format giving you a chance to 
change your mind. It is also a way for you 
to format disks if you only have one drive, 
by asking format to format the disk in 
drive /DO and replacing the system disk 
with the disk you want to format in at this 
point. In either case double check that 
you are about to format the correct disk. 
If you want to be especially safe take your 
system disk out of drive /DO at this point 
even if you are formatting the disk in 
drive one. There is no danger of format 
writing on the wrong disk, but you can't be 
too careful. If you reply N to the READY? 
prompt format will quit immediately leaving 
the disk intact. If you reply Y, there 
will be a pause (23 seconds on my CoCo), 
then format will prompt you for a name for 
the disk. The prompt will look like: 

DISK NAME: 

At this point enter the name you have 
assigned to the disk. The name can be up 




the message 



NUMBER OF GOOD SECTORS: $000276 

If the number is smaller than 276 (a base 
16 number which is 630 in decimal ) some 
sectors were faulty. 

If you want to demonstrate to yourself 

at format did something to the disk try 

-,e FREE command on the new disk. Enter 

ne command FREE /D1. The command line 

shoul d look 1 ike: 

039: FREE /Dl 

The response should be something like: 

disk name CREATED ON 8A/01/2A 

CAPACITY: 630 SECTORS (1-SECTOR 

CLUSTERS) 

620 FREE SECTORS, LARGEST BLOCK 

620 SECTORS 

Where "disk name" in the first line of the 
response will be the name you gave the disk 
when you formatted it. 



BACKUP 

The next command to use after the format 
command is BACKUP. It is crucial to have a 
backup copy of each software distribution 
disk you have. If you make an error that 
damages the only disk with an significant 
piece of software on it you will have to 
wait until you can get a replacement for 
the disk before you can use your computer 
again. Even if the time wasted waiting for 
the replacement disk isn't important to 
you, consider that replacement disks cost 
money . 



Backup is a relatively fast way to cre- 
ate an exact copy of a disk. It has many 
options, but the simplest way to use the 
command is to just give the command BACKUP. 
The command line should look like: 

0S9:BACKUP The response will be: 
READY TO BACKUP FROM /DO TO /Dl 
7 J 

At this point put the disk you want to copy 
in /DO and a formatted disk which has noth- 
ing you want to keep on it in drive /Dl . 
Then check the disk in /D1 ... BACKUP will 
erase anything that's on that disk. When 
you are certain everything is OK type Y. 
Now BACKUP will double check with you by 
telling you the name of the disk in drive 
/D1. The message will look like: 

THE DISK 

IS BEING SCRATCHED 
OK ?: 

If you reply Y to this, the backup from the 
disk in /DO to the disk in /D1 will take 
place. The disk in /D1 will become an 
exact copy of the disk in /DO right down to 
the disk's name. 

The BACKUP command takes what seems 
like a long time to run. There are two 
things that can speed it up. One is to use 
the -V option which prevents the copy from 
being verified. I don't suggest that any- 
one use this option. The other way to 
speed BACKUP up is to instruct 05-9 to give 
it extra memory to run in. BACKUP can use 
extra memory to run more quickly. BACKUP 
ran for one minute 58 seconds when I start- 
ed it with the command line: 

0S9: BACKUP 

Normally BACKUP uses 19 pages of memory. 
If you give it more -- say 100 pages -- 

with the command line: 



0S9: BACKUP #100 



it runs in one minute 48 seconds. It is 
also quieter because the heads on the disks 
don't load and unload as often. 



DIR 

The command which tells you what files are 
one your disks is the the Dir (short for 
directory) command. If you just type DIR 
after booting OS-9 you will get a response 
1 ike 



DIRECTORY OF . 23:55:08 
0S9B00T CMDS SYS 
DEFS STARTUP 



This means that you are listing the current 
directory which is known by the pseudonym 
"." at 11:55:08 in the evening. The files 
in that directory are 059B0DT. CMDS, SYS. 
DEFS. and STARTUP. Now. in fact only 
0S9B0DT and STARTUP are normal files, the 
other three files are subdirectories. Sub- 
directories are such an interesting topic 
that they were the subject of their own 
column some months ago. and won't be cov- 
ered any more than absolutely necessary 
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here. To find out more about the files than 
their names use the command DIR E. 

0S9:DIR E 

which will respond: 



DIRECTORY OF 
ON 



23:59:57 



CREATED 
ATTR 



OWNER 
START 



NAME 
SIZE 






83/06/02 1921 
y^j^ 

83/06/02 1956 
D-EWREWR 
83/06/02 2002 
D-EWREWR 
83/06/02 2002 
D-EWREWR 
83/06/02 2003 
R-WR 



A 

3C 

164 

17F 

1F5 



0S9B00T 

3032 

CMDS 

6A0 

SYS 

AO 

DEFS 

CO 

STARTUP 

E 



then it will stop because the screen is 
full. When you are ready to continue hit 
any key ... I usually press the space bar. 
That was the end of the directory, so all 
you get after you let the output continue 
is a, few blank lines and a new 059 prompt. 

Two of the fields in the DIR E output 
are of no special interest until you become 
an advanced OS-9 user: OWNER, and START. 
The first two fields for each file are the 
date and time the file was created. The 
date is in the usual YY/MM/DD format and 
the time is in HHMM format with hours rang- 
ing from 00 to 23. The attributes field 
contains information about what the file 
can be used for. The main thin© now is 
that files with a D as the first character 
in the attribute field are directories. 
Files with a dash as the first character in 
their attribute field are normal files. 

The other option which can be used with 
the DIR command is X. The X option is a 
short hand way to get the directory of the 
execution directory; that is, the directory 
OS-9 searches -^or programs, like the com- 
mands , you ask i t to run . The command 
1 ine: 

DIR X 

will give you a rather long list of all the 
files in your execution directory. If you 
haven't written any of your own programs, 
this will be a list of all the commands and 
utility programs which came with OS-9. You 
will probably have to press the space bar 
in the middle of the output of this com- 
mand. It is more than one page long. 



data directory is /DO. If you have a sec- 
ond drive (I have been assuming that you 
do) you will probably want to use that for 
data. The command: 

CHD /Dl 

will cause all future references to data 
files to look for them on /D1 . 

To speed OS-9 up, the location of the 
directory file on the disk is kept in memo- 
ry. This leads to the side effect of the 
Chd and Chx commands. When you read the 
directory OS-9 goes directly to the direc- 
tory's location on disk and starts reading 
. . . imagine what would happen if you fooled 
OS-9 by changing disks. You change disks 
and type a command 1 ike 

LIST FOO 

or even just DIR. Your operating system 
will start reading where the directory is 
supposed to be. Since the disk with a 
directory at the selected spot is sitting 
in its envelope and some other disk is in 
the drive, OS-9 will find something unex- 
pected where the directory was. The result 
could be any of several error messages. 
The solution to this problem is to always 
give OS-9 a chance to find the directories 
on a new disk by giving it Chd and Chx com- 
mands as necessary when you change disks. 

There is one last tricky thing about 
the Chx/Chd commands' special use. If you 
keep things simple it will seem that you 
only need to use the Chx command, but this 
is just a special case. I suggest that you 
learn how to make directories and use them 
when you can, but, until you start using 
them, the new disks you use to store data 
will only have the directory FORMAT auto- 
matically creates (called the "root direc- 
tory"). The root directory is always at 
the same location on a disk. Because of 
this special fact about the root directory 
OS-9 Is always able to find it, and chang- 
ing disks that only have the root directory 
on them won't cause any trouble. The exe- 
cution directory is usually not the root 
directory, so this special case doesn't 
generally apply to it. 

The set of commands I have mentioned in 
this column might be considered a "starter 
set" for OS-9. The dozens of commands I 
left out are certainly worth learning, but 
you can get 05-9 working with these few. 



OOPS 



CHX AND CHO 

Chx stands for Change Execution Directory, 
Chd for Change Data Directory. OS-9 
expects to find all commands, whether they 
are part of the operating system or some- 
thing you wrote, in the execution directo- 
ry. All files that you don't mean to exe- 
cute are looked for in the data directory. 
(There are ways around both of these 
restrictions, but let's skip that for now.) 
After you boot OS-9 you will find that the 
execution directory is /DO/CMDS and the 



I neglected to mention a few months ago 
that OF lex as reviewed in this column is 
available only from Gimix. Richard Don, 
the salesman for Gimix, explained the gen- 
eology of OF lex to roe. It is Flex by TSC 
adapted by Richard Hogg to run under OS-9. 
Gimix provides enhanced disk Device Drivers 
to support Flex's requirements, and made 
some enhancements to Richard Hogg's design. 
Anyone who taket, out licenses from TSC and 
Richard Hogg can sell OFlex, but the ver- 
sion I reviewed has features added by 
Gimix . 
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COLUMN EIGHTEEN 



MY LIFE 

I'm afraid this month's column will be a 
little short. I just bought a house. 
Nothing major wrong with it, but I'm living 
1n the first floor while I fix up the 
upstairs. Piles of boxes are everywhere, 
and it seems like everything I need is in a 
box at the center of an unknown pile. This 
disorder has not helped me get a lot of 
computing done. 

I don't mean to turn this column into a 
diary, but there are a few other important 
items. A kitten is helping me write this. 
I got him to help make my house seem home- 
like, but he likes to help type. I enjoy 
his help, but I hope he will switch to 
sleep- in- the- lap mode soon. 

This fall I will finally become a full- 
time graduate student. I have been study- 
ing Computer Science part time for years, 
but it seemed that the field was moving 
ahead faster than I was learning it. It is 
a scary business going back to college 
after being a working man for years, but 
I'm fairly quivering with eagerness. I 
have one more column to write as a free 
man, then I will be a student. I think I 
can get permission to keep writing this 
column. I hope my studies add some spice 
to my writing. 



NON-STANDARD HARDWARE 



dence. The clock and I/O devices are han- 
dled by drivers. The interfaces to the 
drivers are general enough that any reason- 
able hardware can be accommodated. Micro- 
ware will sell the source to several device 
drivers and a few clock drivers. With a 
copy of OS-9 for any machine, a working 
05-9 to build the new OS-9 on, and a col- 
lection of source from Microware it should 
be possible for an experienced programmer 
to adapt OS-9 to any 6809-based machine I 
have heard of . 

It isn't hard to buy a copy of OS-9 to 
customize. Try a few manufactures. When I 
was building crazy systems I did a lot of 
business with AAA Chicagog Comput i ng; they 
might be able to help you. You don't care 
what version of OS-9 you get unless you can 
get one that is already partly compatible 
with your system. You'll have to write a 
clock driver, a disk driver, and, if you 
use an unusual serial chip, a SCF driver. 
If you want to adapt Level Two, you'll have 
to buy a version of OS-9 that is designed 
for the memory management hardware you 
have. Memory management is done in the OS-9 
kernel (0S9P1). It isn't easy to adapt 
without lots of source code ... the kind 
of source Microware sells as part of an OEM 
license ... very expensive. 

If anyone has OS-9 running on unsup- 
ported nardware let me know. Microware 
doesn't officially want to support you, but 
they might not object if we set up a func- 
tion of the Users Group to help you out. 
If there is enough interest, maybe we can 
find a reliable source of adaptable OS-9. 
In any case, I'll report any tips you send 
me in this column. 



A fair amount of the OS-9 mail I get 

asks about special versions of OS-9. Many 

people have old SWTPc systems they would 

like to run OS-9 on. There are also a few 

people with home-brew 6809 systems who'd 
like to port OS-9. The news for these peo- 
ple is mostly bad. 

There used to be a SWTPc version of 
OS-9 Level One, but I don't think it is 
sold any more. DS-9 Level Two is sold only 
through hardware manufacturers, and SWTPc 
hasn't licensed it. If you have your own 
home-brew design, you can 1 icense OS-9 from 
Microware, but the price is ridiculous 
unless you mean to sell it. 

Two years ago (or more) Microware used 
to sell a generic version of OS-9 Level 
One. You could buy it directly from Micro- 
ware and adapt it to whatever system you 
wanted. I guess a few people must have 
purchased that version of OS-9 and tied up 
Microware's hotline for days with the trou- 
ble they had getting it going. The effort 
they had to put into helping people use the 
generic OS-9 was more than Microware could 
afford, so they dropped the product. This 
policy seems to be mainly a way of avoiding 
piracy. The theory is that if the people 
who sell the hardware have to buy the right 
to sell OS-9, they will see to it that peo- 
ple buy an operating system instead of 
steal ing i t . 

Officially there is no way to get OS-9 
for your SWTPc. or home-brew machine. 
Unofficially, there are ways. An important 
features of OS-9 is its hardware indepen- 



D I RECTORIES AS FILES 

A directory is a special type of file, 
If they are handled correctly, they can be 
opened and used without much trouble. If 
you try to list or dump a directory file, 
you will have trouble. Directory files can 
only be opened using the directory access 
mode; and Dump, List, Copy, and most other 
OS-9 utilities don't use this mode. 

The easiest thing to do with a directo- 
ry is to simply read it and copy it to 
standard output. The program called DList 
copies the current directory to standard 
output . You can see the contents of the 
current data directory by assembling DList 
and typing 

0S9: DList ! Dump 

Directories contain many unprintable char- 
acters, so if you don't use Dump to format 
the output you will get gibberish on the 
screen. You may even make your terminal do 
strange things. 



It occurs to me that Radio Shack sells 
the least expensive OS-9 around. Micro- 
ware has a few versions of Level One for 
Motorolla systems that they can sell. 
The Radio Shack OS-9 has a non-standard 
disk format that you can avoid by buying 
the more expensive Motorolla software. 
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I have a directory with only the file 
containing DList in it. I ran DList with 
the command 1 ine: 



0S9:DList ! Dump >tmp 

The contents of Tmp are listed in Figure 6. 



Addr 01 23 A5 67 89 AB CD EF 02468ACE 

0000 2EAE 0000 0000 0000 0000 0000 0000 0000 

0010 0000 0000 0000 0000 0000 0000 0000 01B9 9 

0020 AEOO 0000 0000 0000 0000 0000 0000 0000 

0030 0000 0000 0000 0000 0000 0000 0000 054D M 

0040 746D FOOO 0000 0000 0000 0000 0000 0000 tmp 

0050 0000 0000 0000 0000 0000 0000 0000 0765 

0060 A4AC 6973 FA43 4830 B700 0000 0000 0000 DListCH07 

0070 0000 0000 0000 0000 0000 0000 0000 0763 c 



F i oune 6 : 



Hex dump of a directory 



Each entry in the directory takes two lines 
in the dump. The first two entries are 
self-referencing. The entry is first; 
the name " . . "- (2EAE) is at the beginning of 
the entry. The disk address of the file 
descriptor (0001B9) for the parent of this 
directory is at the end of the entry. The 
second entry is for " . •' (AE) which is the 
alias for this directory. The address 
associated with that (OO054D) points to the 
file aescnptor for this directory. 

The entry for tmp is for the file I put 
the dump into. The last entry looks like 
it is for DListCHOT. but if you look at the 
hex part of the dump you will see that the 
high bit of the *'t" is on, meaning that it 
is the last character in the string. The 
characters "CH07" are an artifact of a pre- 
vious use of the entry for the file 
SCRATCHC7. 

DList could be changed to edit the con- 
tents of the directory before passing it to 
standard output. The first two entries are 
always for "." and "..". There is usually 
no need to notice them. There can also be 
null entries in the directory. When a file 
is deleted the first byte in the directory 
entry is set to $00 making it into a null 
entry. DList could check for null entries 
and suppress them. 

DList2 is an enhanced version of DList. 
It uses I$Seek to skip the first two 
entries, then copies all entries that don't 
start with $00 to standard output. 

The next feature to add would be for- 
matting the output so it could be read 
without using Dump. The address of the 
file descriptor isn't likely to be worth 
seeing often, so the final program. Id, 
just prints the file names. A useful 
directory list program needs to be able to 
list the contents of directories other than 
the current default so I added that func- 
tion. Ld can take a directory name on the 
command line. It wouldn't be too hard to 
add the x option by opening the directory 
with the execution attribute, but that's a 
function I didn't add. The program deter- 
mines whether a directory name was given by 
checking the length of the parameter area. 
If the parameter area is only one byte 
long, it only contains a carriage return, 
otherwise it contains a directory name ter- 
minated with a carriage return. 



It would be nice to add the "e" option 
to the Id command, but an extended directo- 
ry involves lots of numbers and dates. The 
code to format all that information would 
make a long program. Instead, I have writ- 
ten a Basic09 program that takes the output 
of DList2 and generates a more extensive 
report. There is room. for lots of improve- 
ment in DFormat; I only print the file 
name, creation date, last modified date, 
and file size, and I don't sort the list in 
any special order. Improvements like these 
are, as they say. "left for the reader." 

Each directory entry contains the disk 
address of tne file descriptor sector for 
the file. The file aescriptor contains all 
the interesting information about a file. 
We need to read the file aescriptor, but 
all we know is its disk address, and the 
only way to get at a particular sector on a 
disk is with physical -sector I/O. Normally 
physical -sector I/O is done by opening a 
device; e.g. dump /DO^. Since there is no 
easy way to find out the name of the drive 
the directory is on, the /DO^ type of trick 
isn't useful. There is an interesting var- 
iation on physical -sector I/O which I 
haven't been able to find documented any- 
where. If you open the file ^, it will 
open the drive the data directory is on for 
physical I/O. If you open it for execu- 
tion, it will open the drive with the exe- 
cution directory on it for physical I/O. 

Since DListS is feeding this program, 
and DList2 can only read the current data 
directory. DFormat assumes the directory is 
on the same disk as the data directory. 

I ysed a useful trick from the UMIX Is 
command. Directory files are indicated by 
a "/" after them in the listing from DFor- 
mat . 

If you have a UNIX-like sort program 
available the combination of DList2 and 
DFormat can be made even more useful . By 
sorting on the various fields in the output 
from DFormat you can get the listing alpha- 
betically by name, by increasing size, or 
in chronological order, 

If you have RunB type DFormat in, save 
it, and pack it. Then use it with a com- 
mand 1 ine 1 ike : 

0S9:DList2 ! DFormat 
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If you don't have 
something 1 ike: 



RunB, you'll need to use 



OS9:DList2 ! basic09 DFormat 



DLIST PROGRAM 

Microware OS-9 Assembler 2.1 07/13/84 12:07:52 
DList - List the Current Directory 



Page 001 



00001 
00002 
00003 
00005 
00006 
00007 
00008 
00009 
00010 
00011 
00012 
00013 
0001 A 
00015 
00016 
00017 
00018 
00019 
00020 
00021 
00022 
00023 
00024 
00025 
00026 
00027 
00028 
00029 
00030 
00031 
00032 
00033 
00034 
00035 
00036 
00037 
00038 
00039 
00040 
00041 
00042 



0011 
0081 
0000 87CD0043 

D 0000 
D 0001 
D 0021 
D 00E9 

OOOD 444C6973 

0012 01 

0013 2EA0 



0015 
0015 
0017 
OOIB 
OOIE 
0020 
0022 
0022 
0024 
0028 
002B 
002D 
002F 
0032 
0034 
0036 
0038 
0038 
003A 
003C 
003D 
003D 
0040 
0043 



8681 

308DFFF8 

103F84 

251D 

9700 

3041 

108E0020 

103F89 

250B 

8601 

103F8A 

2509 

9600 

20EA 

C1D3 
2601 
5F 

103F06 
69C250 



type 
Revs 



DPath 
Buffer 
Stack 
Memsize 

Name 

Version 

Dirname 

Entry 



RLoop 



TEof 

Error 
MEnd 



nam 

ttl 

IFFl 

ENDC 

set 

set 

mod 

rmb 
rmb 
rmb 
equ 

fcs 
fob 
fcs 



Ida 

leax 

0S9 

bcs 

sta 

leax 

Idy 

0S9 

bcs 

Ida 

0S9 

bcs 

Ida 

bra 

cmpb 

bne 

clrb 

0S9 

EMOD 

equ 



00000 error (s) 

00000 warning (s) 

S0043 00067 program bytes generated 

S00E9 00233 data bytes allocated 

$223F 08767 bytes used for symbols 



DList 

List the Current Directory 

PRGRM+OBJCT 

REENT+1 

MEnd, Name, Type, Revs, Entry, Memsize 



1 

32 

200 



/DList/ 

1 

/. / 



#DIR.+READ. 
Dirname, PCR 
I$Open 
Error 
DPath 

Buffer, U 
#32 
i$Read 
TEof 

I$Wrxte 
Error 
DPath 
RLoop 

#E$EOF 
Error 



Directory path number 
buffer for directory entries 



Std output 



F$Exit 



return 
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1LIST2 PROGRAM 

iicroware OS-9 Assembler 2.1 07/13/84 12:08:17 
.>List2 - List the Current Directory 



Page 001 



.0001 
J0002 
00003 
D0005 
00006 
00007 
00008 
00009 
00010 
00011 
00012 
00013 
00014 
00015 
00016 
00017 
00018 
00019 
00020 
00021 
00022 
00023 
00024 
00025 
00026 
00027 
00028 
00029 
00030 
00031 
00032 
00033 
00034 
00035 
00036 
00037 
00038 
00039 
00040 
00041 
00042 
00043 
00044 
00045 
00046 
00047 
00048 
00049 
00050 
00051 



0011 
0081 
0000 87CD0057 

D 0000 
D 0001 
D 0021 
D 00E9 

OOOD 444C6973 

0013 01 

0014 2EA0 



0016 
0016 
0018 
OOIC 
OOIF 
0021 
0023 
0025 
0028 
002B 
002E 
0030 
0032 
0032 
0034 
0034 
0038 
003B 
003D 
00 3F 
0041 
0043 
0046 
0048 
004A 
004C 
004C 
004E 
0050 
0051 
0051 
0054 
0057 



8681 

308DFFF8 

103F84 

2530 

9700 

3440 

CE0040 

8E0000 

103F88 

3540 

251F 

3041 

108E0020 

103F89 

250F 

6D41 

27F3 

8601 

103F8A 

2509 

9600 

20E6 

C1D3 
2601 
5F 

103F06 
C80070 



type 
Revs 



DPath 
Buffer 
Stack 
Hemsize 

Name 

Version 

Dirname 

Entry 



RLoop 
RLoop2 



TEof 

Error 
MEnd 



nam 

ttl 

IFPl 

ENDC 

set 

set 

mod 

rmb 
rmb 
rmb 
equ 

fcs 
fcb 
fcs 



Ida 

leax 
0S9 
bcs 
sta 

fshs 
du 
Idx 
0S9 

Euls 
cs 



Idy 
0S9 
bcs 
tst 
bee 
Ida 
0S9 
bcs 
Ida 
bra 

cmpb 

bne 

clrb 

0S9 

EMOD 

equ 



00000 error (s) 

00000 warning (s) 

$0057 00087 program bytes generated 

S00E9 00233 data bytes allocated 

$224E 08782 bytes used for symbols 



DList2 

List the Current Directory 



PRGRM+OBJCT 

REENT+1 

MEnd , Name , Type , Revs , Entry , Hems ize 



1 

32 

200 



/DList2/ 

1 

/. / 



Directory path number 
buffer for directory entries 



#DIR.+READ. file access mode 
Dirname, PCR file name "." 
I$Open 



Error 
DPath 
U 
#32*2 

h 

I$Seek 

U 
Error 



leax Buffer,!} 



#32 

I$Read 
TEof 

Buffer, U 
RLoop2 

H 

I$Write 
Error 
DPath 
RLoop 

#E$EOF 
Error 



F$Exit 



save the path number 
save U 



skip over 
restore U 



and 



entries 



null entry? 

yes: skip it and read again 

Std output 

directory path 
read again 

Is this EOF? 

no; error 

yes; return happy 

return 
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LD PROGRAM 

Microware OS-9 Assembler 2.1 07/13/8A 12:08:29 
Id - List Files in a Directory 



Page 001 



00001 








nam 


Id 




00002 








ttl 


List Files 


in a Directory 


00003 








IFPl 






00005 








ENDC 






00006 


0011 




type 


set 


PRGRM+OBJCT 


00007 


0081 




Revs 


set 


REENT+1 




00008 


0000 


87CD0072 




mod 


MEnd,Name,' 


Fype , Revs , Entry , Mems ize 


00009 














00010 D 


0000 




DPath 


rmb 


1 


Directory path number 


00011 D 


0001 




Buffer 


rmb 


32 


buffer for directory entries 


00012 D 


0021 




Stack 


rmb 


200 




00013 D 


00E9 




Memsize 


equ 


, 




0001 A 














00015 


OOOD 


6CE4 


Name 


fcs 


/Id/ 




00016 


OOOF 


01 


Version 


fcb 


1 , 




00017 


0010 


2EA0 


Dirname 


fcs 


/. / 




00018 














00019 


0012 




Entry 








00020 


0012 


10830001 




cmpd 


DirNGivn 


length of parameter string 


00021 - 


0016 


2204 




bhi 




00022 




* 


If more 


than 


one byte of 


parameters 


00023 




* 


assume 


file name oh command line. Otherwise use "." 


00024 


0018 


308DFFF4 




leax 


Dirname, PCR use "•" as directory 


00025 


OOIC 




DirNGivn 








00026 


OOIC 


8681 




Ida 


#DIR.+READ 


. file access mode 


00027 


OOIE 


103F84 




0S9 


ISOpen 




00028 


0021 


2532 




bcs 


Error 




00029 


0023 


9700 




sta 


DPath 


save the path number 


00030 


0025 


3440 




pshs 
Idu 


U 


save U 


00031 


0027 


CE0040 




#32*2 
#0 




00032 


002A 8E0000 




Idx 




00033 


002D 


103F88 




0S9 


I$Seek 


skip over , and •. entries 
restore U 


0003A 


0030 


3540 




puis 

DCS 


U 


00035 


0032 


2521 




Error 




00036 


003A 




RLoop 








00037 


003A 


3041 




leax 


Buffer, U 




00038 


0036 




RLoop2 








00039 


0036 


108E0020 




Idy 
0S9 


#32 




OOOAO 


003A 


103F89 




ISRead 




OOOAl 


003D 


2511 




bcs 


TEof 




000A2 


003F 


6D41 




tst 


Buffer, U 


null entry? 


000A3 


00 A 1 


27F3 




beq 


RLoop2 


yes: skip it and read again 
Prepare file name for printing 


OOOAA 


00A3 


8D13 




bsr 


Edit 


000A5 


00A5 


8601 




Ida 


I$WritLn 


Std output 


000A6 


00A7 


103F8C 




0S9 




00047 


OOAA 


2509 




bcs 


Error 




000A8 


OOAC 


9600 




Ida 


DPath 


directory path 


000A9 


OOAE 


20E4 




bra 


RLoop 


read again 


00050 


0050 




TEof 








00051 


0050 


C1D3 




cmpb 


#E$EOF 
Error 


Is this EOF? 


00052 


0052 


2601 




bne 


no; error 


00053 


005A 


5F 




clrb 




yes; return happy 


0005 A 


0055 




Error 








00055 


0055 


103F06 




0S9 


F$Exit 


return 


00056 


0058 




Edit 








00057 


0058 


5F 




clrb 






00058 


0059 




ELoop 








00059 


0059 


6D85 




tst 


B,X 




00060 


005B 


2B07 




bmi 


ELoopX 




00061 


005D 


270B 




beq 


EError 


A name can't end in a null 


00062 


005F 


5C 




incb 






00063 


0060 


CUD 




cmpb 


#29 
ELoop 




0006A 


0062 


25F5 




bio 


A name can't be more than 29 b 


00065 


0064 




ELoopX 








00066 


0064 


860D 




Ida 


#$0D 


<CR> 


00067 


0066 


5C 




incb 






00068 


0067 


A785 




sta 


B,X 




00069 


0069 


39 




rts 
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Hicroware OS-9 Assembler 2.1 07/13/84 12:08:32 
Id - List Files in a Directory 

EError 



MEnd 



00070 


006A 




00071 


006A 


860D 


00072 


006C 


A784 


00073 


006E 


39 


0007A 


006F 


6FABBC 


00075 


0072 





Ida 


#$0D 


sta 


,x 


rts 




EMOD 




equ 


i: 



Page 002 



Return null line for errors 



00000 error (s) 

00000 warning (s) 

$0072 OOllA program bytes generated 

$00E9 00233 data bytes allocated 

$2299 08857 bytes used for symbols 



DFORMAT PROGRAM 



PROCEDURE 
0000 
OOIB 
0031 

0070 
0079 
0082 
0089 
0094 
00B6 
00C2 
00C4 
OOCD 
00D3 
0102 
013E 
014E 
0164 
0177 
Oi7B 
0186 
01B9 
OICC 

01F4 
0203 
020D 
0216 
0225 
022B 
022D 



0265 

029C 

02D2 
02D6 
02E9 
02EF 
0309 
030F 
0311 
0315 
032A 
032C 
032E 



DFormat 
TYPE dirfint=naine : STRING [29] ; lsn(3):BYTE 
TYPE SegLFmt=SLsn(3) :BYTE; SegLen: INTEGER 
TYPE fdfmt=attr:BYTE; owner : INTEGER: ModDate (5) ,LinkCt , 

FileSize(4) ,CDate(3) :BYTE; SegList (48) :SegLFmt 
DIM DirEnt:dirfffit 
DIM FD:fdfmt 
DIM Real LSN:REAL 
DIM i,errnuin: INTEGER 

DIM PPath:BYTE \REM Physical 10 path number 
OPEN #PPath,"@*':READ 
LOOP 

GET #0,DirEnt 

ON ERROR GOTO 10 

REM Change name from assembler string format to 

REM Basic09 string format by plunking a $00 at the end 

FOR i«l TO 29 

EXITIF ASC(MID$(DirEnt.name,i,l))>127 THEN 

DirEnt,name*LEFT$(DirEnt,name, i) 
ENDEXIT 
NEXT i 

REM change the LSN of the FD sector from three bytes 
REM to a real number • 

Real LSN=DirEnt.lsn(3)+256-(DirEnt.lsn(2)+256^ 

DirEnt.lsn(l)) 
SEEK #PPath,Real LSN*^256 
GET #PPath,FD 
PRINT DirEnt.name; 
IF FD.attr>127 THEN 

PRINT *7"; 
END IF 

*' "; FD. ModDate (1): "/"; FD. ModDate (2) ; »7"; 

FD.ModDate(3) • '^ ''; FD,ModDate(4) ; 
"-"; FD. ModDate (5;; " "; FD.CDate(l); •'/*'; 
FD.CDate(2); "/*"; FD.CDate(3); 



10 



of it, 



PRINT 
PRINT 
PRINT 



, FD.FileSize(4)+256'^(FD.FileSize(3)+256'^ 
(FD.FileSize(2)+256'^FD.FileSize(l))) 



ENDLOOP 

REM error handler 

errnum=ERR 

IF errnum-211 THEN \REM end of file 

CLOSE //PPath 

END 
ELSE 

PRINT "Error number "; errnum 

END 
ENDIF 
END 
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COLUMN NINETEEN 



MORE GAMES WITH DIRECTORIES 

Last month I discussed reading from direc- 
tory files. This month I'll stay with 
directories and add some additional tricks. 

The directory formatting command at the 
end of this column is a useful version of 
the DIR command. It doesn't illustrate any 
ideas that weren't covered in last column, 
but it is a single program that is faster 
to use than the pipeline of programs I pre- 
sented last month. 

I have found that C is a good language 
to write quick system level programs. Of 
course, assembly language still has some 
advantages over any high-level language; 
not least that almost everyone with OS-9 
has an assembler. A functional directory 
command in assembler would be just too long 
for one month's column, and not interesting 
enough to devote several months to. So the 
first program for this column is an inte- 
grated directory formatting command. It is 
written in C. It could be translated to 
Basic09 without too much trouble, but that 
would require loading BasicOS every time 
you want to list a directory. Sorry, peo- 
ple without C. 

Radio Shack is selling Microware C at 
an impressively low price. It is a good 

investment . 

Think of dr as a good starting point. 
It is easy to get it to sort its output. 
Adding the ability to select only files 
that meet certain criteria for display is 
harder but useful enough to be worth the 
effort. Working this up into a full -screen 
command environment is something I've been 
promising myself time to do ..., but I 
haven't yet. 

You can write directories as well as 
read them. There are good reasons to do 
this. Renaming files is one reason. The 
rename command simply writes a new name 
over the old one in the directory. Delet- 
ing and creating files are other reasons to 
write into directory files, but RBFMan 
takes care of those operations. Most other 
things you would want to change about a 
file involve writing into the file descrip- 
tor sector for the file. That's just as 
easy as writing the directory. Easier. 

There is an easy way to make C read a 
directory file, but there is no equivalent 
method for updating directory files. The 
combination of attributes required to write 
into a directory can be used from assem- 
bler, or from the lower level parts of C, 
but it seems Microware wanted to make it a 
bit tricky to mess with directories. 
Before I continue let me add to their 
implicit warning. If you are not brave and 
experienced don't even think of updating a 
directory file! 

Writing on directory files is a danger- 
ous thing to do. If you make a mistake you 
can loose files, or even mess up the struc- 
ture of the entire disk. DON'T jump in and 
try programs that write to the directory on 
an important disk. 



After making certain that your program 
doesn't damage the directory under normal 
circumstances, think about extraordinary 
situations. How does the program behave if 
the system crashes right in the middle of 
the change? Can trouble start if two pro- 
grams try to make a change at the same 
time? What will a program reading the 
directory while you make your change see? 

Another area where you can get in trou- 
ble and discover interesting new possibili- 
ties hidden In the OS-9 file structure is 
the possibility for having several directo- 
ry entries pointing at the same file. 

There is a link count in each file 
descriptor sector. This count will always 
be one in normal OS-9 systems, but the 
field offers a way to tell OS-9 (RBFMan) 
that there are two or more directory 
entries pointing at a file. 

This trick will certainly cause DCHECK 
to have fits. If you link two directory 
files to one another (not just with the 
file name) DCHECK will loop between the two 
directories forever. Even if you don't get 
this extreme DCHECK will note that more 
than one file is using the clusters belong- 
ing to the file with which you're playing. 
I have a deadly fascination with this trick 
of linking to a file several times. The 
parts to put it together are all there, but 
for some reason Microware hasn't built it 
into OS-9 yet. 

My bet is that the reason for multiple 
links to files remaining dormant in OS-9 is 
the recovery problem this feature creates. 
It is impossible to update the link count 
in the file descriptor and change the num- 
ber of directory entries pointing to a file 
simultaneously. There is always some way 
to crash the system between the two opera- 
tions -- pulling the plug will work. 

If the link count is greater than the 
number of directory entries actually linked 
to the file, the file will eventually be 
left around with no directory entries 
pointing at it. The disk space for the 
file will be allocated and there will be no 
easy way to return them. 

If the link count Is smaller than the 
number of directory entries linked to the 
file the result is worse. Eventually there 
will be a directory entry pointing to a 
file that isn't there. The sectors that 
used to belong to the file could be part of 
another file or just free; in either case 
the result is chaos. 

It looks impossible. There is trouble 
whether the file descriptor is updated 
before or after the directory. There are 
two solutions. 

One possibility is to live with the 
problem. An experienced user can fuss 
around with the allocation map and directo- 
ry entries, and repair a damaged disk. 
Most of the work can be automated. Comput- 
ers don't crash often. Chances are they 
won't crash in the middle of a directory 
operation. . . . 

The alternative is to use "stable stor- 
age" tricks. Every time OS-9 starts up 
look for evidence of a crash, and every 
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time you update a directory prepare for 
one. This slows directory updates, systems 
startup, and even disk mounts; but it pre- 
vents users from having to worry about 
recovery. 



Neither method sounds 05-9-1 ike. I use 
the "live with the problem" method. I've 
never had reason to regret 
prepared for the worst . The 
age" method is interesting 
brief discussion. 



it, but I am 
"stable stor- 
. . . worth a 



Here is a way to reliably update a 
di rectory: 

1. Copy the entire directory including 
file descriptors to a special spot, 
with its address known to recovery 
routines (in a table located at 
some known spot ) . 

2. Update the copy of the directory. 

3. Put the address of the old directo- 
ry in the same table as the address 
of the new one with a mark indicat- 
ing that it is old. 



Put the address of 
directory in the 
parent . 



the updated 
directory' s 



Remove the new directory from the 
table . 

Delete the old directory removing 
it from the table. 



Step 4 involves a single operation that 
changes the directory structure visible to 
the public. Until step 4 is executed no 
program knows about the change. After step 
4 there is a consistent updated directory. 

Recovery works as follows: 

IF THERE ISN'7 ANYTHING IN THE "TABLE" 

no recovery necessary 

• IF THERE IS A POINTER MARKED "OLD" AND 
NO NEW POINTER 

delete the old directory 

• IF THERE IS ONLY A NEW DIRECTORY IN 
THE TABLE 

delete it. 

IF BOTH POINTERS ARE 'iN THE TABLE 

continue from step 4 in the update 
procedure 

Things fall apart again if two process- 
es might simultaneously update the directo- 
ry, or the file descriptors attached to it. 
If that is permitted the protocol gets com- 
plicated. Too complicated for this column. 

I'm not going to try to present a pro- 
gram implementing stable storage this 
month. (Just a simple program to squeeze 
the null entries out of a directory. 
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DR PROGRAM 

//incl 
2 //include <ctype.h> 
f/incl 



1 #include <stdio.h> 

#incli 

#incli 

4 //include <direct.h> 

5 

6 

7 static struct dirent DirEntry; 

8 static_FILE '^fopenQ, '^dir, *disk; 

10 1 ^^ , , . directory read * 

11 7 Read and format all the important fields in a *'^ 

12 Y directory entry and the attached FDs. *'^ 

13 ^ To allow formatting, sorting, and searching programs* 
lA ^ the best access to this data it is just printed * 
15 2 without titles, ^ r ^ 
}6 There are no options. A directory name may be given* 
17 ^ as a C9mmand line argument. If it isn't the current* 

lo ^ data directory will be listed. * 

29 ?v-. ^. 

20 main(argc,argv) 

21 int argc; 

22 char *argv[] ; 

2A char temp [120]: 

25 char device [30J ; 

26 • register int i; 

28 

29 pflinitO; 

30 argv++; /^ bump past program name in args*/ 
il if large > 1) 

32 strcpy(temp.*argv) ; 

33 else 

3A strcpyCtemp,".") ; /* default directory */ 

36 if((dir = fopenCtemp, "d")) «- NULL) /* open the directory */ 

38 fprintf (stderr,"Xs can't be read as a directory\n", temp) ; 

39 exitU); 

40 } 
41 

42 

f»3 strcpy(deyice,y@"); /* default device is data directory device */ 

44 if (temp [0] «='/') 

45 1 

46 i «= 0: 

47 do 

48 device [i] * tempFi]; 

49 while (isalnum(temp[++i]) temp[i] -- \' 11 temp [i] =-''): 

50 device .i++J = '?' ; ' ' ^ - ' 

51 deviceLi] « '\0'; 

52 fprintfCstderr, "Device: visXn" , device) ; 

54 

55 /* * 

56 * Open the device containing the directory * 

57 * we're about to list. * 

59 ' 

60 if ((disk = fopen (device, "r")) ~ NULL) 

61 { 

62 fprintf(stderr, "Error Xd opening device s\n", ferror (disk) , device) ; 

63 exit(l); 

64 i 
65 

66 fread(&DirEntry, sizeof DirEntry, 1, dir) ; /* skip . entry */ 

67 fread(&DirEntry, sizeof DirEntry, 1, dir); /* skip " 



68 

69 /* ^ 

70 * Read and format directory entries until EOF* 

71 * Null entries are ignored by putEntry. * 

72 * */ 

73 while (fread(&DirEntry, sizeof DirEntry, 1, dir) != NULL) 

74 putEntry (DirEntry.dir_name,DirEntry.dir_addr) ; 

76 exit(O); 

78 

79 

80 putEntry (Name , Address) 



entry */ 
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81 char "Name, ^Address; 

82 { 

83 char CName [30] ; 

84 long LSN; 
85 

86 if (Name [0] " '\0') 

87 return; /* Null entry 'V 
88 

89 fixname (CName, Name) ; /" change OS-9 string (high-bit) 

90 to C format string 'V 
91 

92 13tol (&.LSN, Address, 1) ; r- make LSN usefuU 'V 

93 

9A printfC'Xs*', CName); /'" reformatted file name ^1 

95 

96 expansion(LSN) ; /^' rest of the information */ 

97 

98 , return; 

99 } 
100 

101 static struct fildes FD; 
102 

103 expansion (LSN) /^ print everything interesting about a file */ 

104 long LSN; 

105 I 
106 

107 if (f seek (disk, LSN'^256, 0) ~ EOF) 

108 1 

109 fprintf (stderr, *'Disk seek error 'yidXn", f error (disk) ) ; 

110 , exit(l); 

111 } 

112 if (fread(&cFD, sizeof FD, 1, disk) " NULL) 

113 1 

114 fprintf (stderr, "Disk read error %d\n*', f error (disk) ) ; 

115 , exit(l); 

116 } 
117 

118 format attr(FD.fd att): 

119 printfT" •/iu'',FD.fa own): 

120 format date(FD.fd Hate, 5); 

121 printft" %d '/:id",FD.fd link, FD.fd f size) ; 

122 format date (FD.fd dcr, 3) ; 

123 printfT"\n"); 

124 , return; 

125 } 
126 

127 
128 

129 fixname (goodname,badname) 1'^ convert from OS-9 string to C string "*' I 

130 char '^goodname,*badname; 

131 i 

132 register int i; 
133 

134 i - 0; 

135 do , 

136 { 

137 , '^goodname++ = '^badname h. *\x7f'; 

138 } 

139 while ((*badname++ > 0) &6r (++i <= 29)); 
140 

141 *goodname = '\0' ; 

142 , return; 

143 } 
144 

145 format attr(attr) /'^ print file attributes ^/ 

146 char attr; 

147 I 
148 

149 if (attr & S IFDIR) /* is it a directory? */ 

150 printfC'T [ d"); 

151 else 

152 printfC' [") ; 
153 

154 if (attr & S ISHARE) 

155 printf(""ps"); 

157 if (attr & S lOEXEC) 

158 printf("~pe*'); 
159 

160 if (attr & S lOWRITE) 

161 printf("-pw"); 
162 
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163 ifCattr & S lOREAD) 

16A printf("-pr"); 
165 

166 ifCattr & S lEXEC) 

167 printf ("-e"); 
168 

169 ifCattr & S IWRITE) 

170 printf ("~w"); 
171 

172 ifCattr & S IREAD) 

173 printf (""r"); 
17A printf ("J"); 

175 , return; 

176 } 
177 

178 format date (date, x) /* print a date in readable form */ 

179 char '-date; /" yymmdd (hhmm) */ 

180 int x; /* number of entries in the date array */ 

181 I 

182 char *month name ; 
183 

184 printfC (%d 'is 19*/C02d",date [2] , month name (date [l] ) , date[0]); 

185 i£(x >- 5) ~ 



186 printf (" %d:*>C02d", date [3] , date [A]); 

187 printf (")"); 

188 , return; 

189 } 
190 

191 

192 char *month name (n) /* return name of n-th month */ 

193 int n; ~ 

195 static char "name [j = 

196 1 

197 "illegal month", 

198 "January", 

199 "February'', 

200 "March", 

201 "April", 

202 "May", 

203 "June'', 
20A "July", 

205 "August", 

206 "September", 

207 "October", 

208 "November'', 

209 , "December" 

210 }; 
211 

212 , return(( n < 1 1 n > 12) ? name [0] : name [n] ) ; 

213 } 
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DIRSQZ PROGRAM 

1 //include <stclio.h> 

2 //include <direct.h> 

3 //include <DDodes.h> 
A 

5 static struct dirent DirEntry; 

6 static int dir; /^^ path number "^ / 

8 /': DirSqz 'V 

9 /" This program can be used to press the null 

10 entries out of large directories that have 

11 been hit with many deletions. 

12 "/ 

13 mainO 

15 long strt ptr, end ptr, backupC); 
16 

17 pflinit : 

18 if((dir - open(*'/', S IFDIR+S IREAD+S IWRITE)) «= NULL) 

19 i - - - 

20 fprintf (stderr, "Error opening the directory >id\n", f error (dir)) ; 

21 ^ exit(l); 

22 } 

23 strt ptr = sizeof DirEntry '^ 2; /* point past . and .. */ 
2A getslat(2, dir, &end_ptr) ; /^' length of the file 'V 

25 end_ptr -= sizeof DirEntry; /* point back from end */ 

26 end_ptr = backup (end_ptr ,strt_plr) ; 

28 for(;strt ptr < end ptr; strt ptr ^^ sizeof DirEntry) 

29 { - ^ ~ ^ ~ 

30 Iseek (dir, strt ptr,0); 

31 read(dir, 6(DirEntry, sizeof DirEntry); 

32 if (DirEntry. dir name [0] " *\0') 

33 T - ^ 

3A end_ptr = backupCend ptr, strt otr) ; 

35 /**^ leaves DirEntry with good data '^Z 

36 if (end ptr <« strt ptr) 

37 break; 

38 Iseek (dir, strt ptr, 0); 

39 write (dir, ^DirEntry. sizeof DirEntry); 

40 Iseek (dir, end ptr, 0); 

41 write(dir, "","1); 

A2 ^ end ptr « backup(end ptr, strt ptr); 

43 , } " " 

44 } 

45 , exit(O) ; 

46 } 
47 

48 
49 

51 long backup (end_ptr,strt_ptr) 

52 iong end ptr, strt ptr; 

54 forC;end_ptr >«= strt_ptr ; end_ptr -= sizeof DirEntry) 

56 Iseek (dir, end ptr, 0); 

57 read(dir, &DirEntry, sizeof DirEntry); 

58 if (DirEntry. dir_name[OJ != '\0') 

59 , break; 

60 } 

61 return (end_ptr) ; 



62 
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A REVIEW OF 0"F 



A few weeks ago I spent most of a Saturday 
hooking my old SWTPC FLEX machine to my new 
machine as a remote computer so I could use 
it to write a FLEX-format disk. It felt 
rather odd using my "smart terminal" pro- 
gram to communicate with a machine less 
than a foot away. The process involves 
shuffling disks drives back and forth, and 
much opening and shutting of cabinets. I 
don't like it much. My new machine has 
GIMIX software switching, so I can run FLEX 
on it, but even the remarkable GIMIX CPU 
board can't run both operating systems at 
once. On occasion I have uploaded a file 
from one OS to an IBM and then downloaded 
it with the other OS. accomplishing a 
change of disk format from FLEX to OS-9 or 
vice-versa. These methods are all inele- 
gant, ad hoc solutions to a problem. Dr. 
Matthew Scud i ere has come up with a much 
cleaner solution: He has written an 
0S-9/FLEX copy program called 0-F . 



GENERAL SYSTEM DESCRIPTION 

This 0S9/FLEX copy program is a BASIC09 
program which allows the user to convert an 
OS-9 format disk into a hybrid form which 
can be read and written by FLEX. In the 
process of doing this it makes the disk 
inaccessible to OS-9 except as an entire 
disk (i.e. /DnP) but 0-F is able to copy 
files to and from the hybrid disk, and read 
the FLEX directory. The disk that results 
from the reformatting is enough like stan- 
dard FLEX format that FLEX doesn't know the 
disk isn't one of its own. 



be possible to just 
1 ists 7 options: 



run it. The program 






Di rect ions 


1 


FLEX Directory 


2 


Copy FLEX text file to 0S9 


3 


Copy 0S9 path to FLEX 


4 


Delete FLEX File 


5 


Reformat 0S9 Disk 


6 


Exit program 



and prompts for a selection. "Directions" 
produces a quick summary of the function of 
the program, about half a screen full. 
"FLEX Directory" lists the basic informa- 
tion in the directory of a pseudo-FLEX 
disk; file name, Begin, End, Size, and 
date. It also gives the number of sectors 
used on the disk, and the number of sectors 
left. The "Copy FLEX text file to 0S9" dia- 
1 ogue 1 s : 

FLEX Compatible source Drive ID 

FLEX file name to copy — 

Copy to 0S9 destination path — 

The "Compatible source Drive ID" is the 
device name for the disk that has been ref- 
ormatted; that wasn't too clear to me. The 
"Copy 0S9 path to FLEX" dialogue is: 

Drive ID ~ 

FLEX File name to write (Caps) 

Copy FROM 0S9 SOURCE path — 

To delete a FLEX file, select 4, then: 

Flex compatible source Drive ID 

FLEX file name to delete (use 
proper case) — 



LIMITATIONS 

Only freshly formatted, single sided 5 or 6 
inch disks with no bad sectors can be used, 
and there is no way to use a disk which is 
in real FLEX format (formatted by the FLEX 
NEWDISK or FORMAT program). The FLEX to 
OS-9 copy part of the program expands tab 
characters into strings of blanks by 
default, but there is an option which caus- 
es the file to be copied intact. Of course, 
this program doesn't make any attempt to 
convert FLEX programs into OS-9 programs. 
That is work for other programs. 



OPERATION 

In order to run 0-F you must first start 
Basic09. The version I tested was in source 
form, so I had to load it and run it. If it 
is distributed as Basic09 I -Code it should 



The dialogue for reformatting a 
very cautious: 



disk is 



Drive ID — 

Are you sure? — 
Overwrite — <old volume name> 

Are you sure? — 
5-in or 8-in disk? — 

I tried reformatting and writing on 5 inch 
disks (SS/SD, SS/DD, 40 track and 80 
track), and 8 inch disks of all permuta- 
tions. It worked on the 5 inch disks, and 
on SS single and double density 8 inch 
disks. I was able to read psuedo-FLEX files 
created by 0-F from FLEX without any trou- 
ble. 0-F had no trouble reading files 
written by FLEX on disks reformated by 0-F. 
The reformatted disks were also fully usa- 
ble in FLEX. FLEX truly thinks the refor- 
matted disk is one of its own. One nice 
touch is that the program puts two entries 
in the OS-9 root directory of the reformat- 
ted disk: 



** NO 0S9 Files Allowed 



AA 



(This is a FLEX copy disk) 



These entries appear if you do a DIR com- 
mand on the reformatted disk, letting you 
know very quickly that this disk is spe- 
cial . 



EVALUATION 

This is a competent and very useful pro- 
gram. It is especially well equipped with 
error messages and informative text. In 
fact, although it came without a manual, I 
was able to follow the built-in directions 
without any trouble. I do hope that a manu- 
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al is available by the time this program 
hits the market. A program without a manual 
seems somehow unbalanced even If it is usa- 
ble without documentation. A nice extra is 
*hat it appears that this program may be 
distributed in source form. 

0-F works by tricking FLEX, This 
together with the variety of disk formats 
that FLEX might use forces the program have 
some oad restrictions. The most serious 
limitation is the restriction to specially 
formatted disks. It certainly would be nice 
to be able to drag out a four year old FLEX 
disk and read it with this program. The 
restriction to single sided disks is rea- 
sonable in the context of copying files 
from one format to the other. For some 
people the most important limitation will 
be the language requirement. Since this is 
a Basic09 program, you must have BasicOS to 
DG able to run it. It could be a measure of 
the desperate need for a program like this 
one that it is being hustled out in BasicOS 
form . 

One of 0-F's strongest points is the 
cautious approach it takes to the user. 



This program doesn't know how to deal with 
double sided disks, but it doesn't just 
tell you so, it won't let you use them. You 
get a message clearly telling you that 
double sided disks are not-ok if you try. 
Similar messages appear if you try to use a 
disk that 1s flawed in a number of other 
ways . 



SUMMARY 

O-F 1s available from DATA-COMP. It isn't 
really a program of general interest 
there are probably some 05-9 users who 
don't have FLEX or friends with FLEX. 
Those people have very little use for this 
program. The group of people this program 
should prove most useful to are the owners 
of software-switching machines. Using this 
program they can conveniently transfer data 
between operating systems. There are a lot 
of FLEX users out there -- our close rela- 
tives in the computer world. It is good to 
be able to exchange disks with them even if 
we have to be the ones to provide the 
disks . 
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REVIEW OF OS-9 CIS COBOL 



ENHANCEMENTS 



OVERVIEW 

COBOL is a big language, an old lan- 
guage, and an extremely popular language. 
Some languages were designed to be compiled 
and run on small computers; COBOL was not. 
COBOL is vehemently detested by many people 
involved with computers, but, despite all 
the nasty publicity it gets, COBOL is prob- 
ably the most used computer language in the 
world. If you need to hire an experienced 
programmer for a business application, you 
will find the hunting best if you shoot for 
a COBOL programmer . COBOL was one of the 
first compiled languages developed for com- 
puters (around 1960), and it has been being 
(arguably) improved since then. The fully 
"improved" version of COBOL is an enormous 
language whose compiler is fully capable of 
needing the best part of a megabyte of mem- 
ory to run properly. 

There are standards against which any 
version of COBOL should be measured. ANSI 
(American National Standards Institute) has 
defined a COBOL standard which constitutes 
the official definition of the language. 
CIS COBOL was written to conform to the 
ANSI standard definition of COBOL. 

To quote the manual : "CIS COBOL is ANSI 
COBOL as given in 'American National Stan- 
dard Programming Language COBOL' (ANSI 
X3.23 1974)." It includes level 1 of the 
ANSI definition of COBOL along with a few 
parts of level 2. This doesn't mean that 
CIS COBOL is the version of the language 
you may have used on a mainframe computer, 
but it does mean that if you don't use the 
enhancements that CIS COBOL includes, the 
programs you write using it will run essen- 
tially unmodified on any other computer 
that runs level 2 or higher of ANSI COBOL. 
Also, since CIS COBOL is compiled to inter- 
mediate code, programs written in it can be 
run on any computer that has the appropri- 
ate interpreter. If you read the adds in 
BYTE, you will see that CIS COBOL is imple- 
mented for many computers. 

I didn't test CIS COBOL exhaustively 
for conformance to the standard, but I did 
write a few programs in It. I am used to 
IBM's VS-COBOL, and a version of UNIVAC 
COBOL; both are highly enhanced versions of 
higher levels of ANSI COBOL than CIS COBOL. 
It took me a while to learn which of my 
favorite programming tricks aren't possible 
under level 1 of ANSI COBOL, but, after I 
learned the limitations I had to live with. 
I found that I could write programs with no 
more difficulty than I usually experience 
when writing in COBOL. I wish I had been 
able to transfer a program from the IBM to 
my micro and compile it, but I don't know 
of any real programs written to be compiled 
by ANSI level 1 COBOL. Transferring a pro- 
gram in the other direction is no problem. 



Standard COBOL doesn't support the 
interactive microcomputer environment very 
well, but CIS COBOL includes enhancements 
to the ACCEPT and DISPLAY statements that 
make it relatively easy to display screens 
of data, and accept data from fields 
defined on the screen. Information can be 
accepted from, or displayed at. a particu- 
lar cursor location. An input field can be 
defined as numeric only, in which case any 
inappropriate characters (like "A") won't 
be accepted. When a field is filled with 
data, the cursor automatically jumps to the 
beginning of the next field. There are 
special keys which jump the cursor forward 
and backward a field at a time. Special 
function keys can be defined. They act 
like a carriage return (terminate entry 
into a screen), but a program can determine 
whether a screen was terminated by a car- 
riage return or a function key, and which 
function key was used. The location of the 
cursor when carriage return was pressed is 
also available. The net effect of these 
enhancements is that it is fairly easy to 
write CIS COBOL programs that accept and 
display screens of data. 

In addition to the usual COBOL file 
organizations (including ISAM), CIS COBOL 
allows an organization they call "line 
sequential." Line sequential files are 
variable length record files, in which the 
records are terminated by carriage returns. 
This makes it easy to read and write files 
that Pascal would call "files of text." The 
most generally important examples of files 
of this type are files created by text edi- 
tors, and line by line output to a terminal 
or printer. The other access modes sup- 
ported by CIS COBOL are: sequential, rela- 
tive, and indexed. The names of files can 
be specified at run time using statements 
1 ike: 

SELECT FILE-15 ASSIGN TO 
FILE-15-NAKE. 

ACCEPT FILE-15-NAME. 
OPEN INPUT FILE~I5. 

In addition to the standard ANSI debug fea- 
tures. CIS COBOL has a respectable interac- 
tive debugger. The commands available 
under this debugger are: 



There is far too much to CIS COBOL for 
me to say with certainty that it all works, 
but I understand that the language has 
actually been successfully tested against a 
set of standard test programs . 
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P - Display the current program counter 

G - Set a breakpoint 

X - Single step 

D - Display data at specified offset in data division 

A - Change memory (ASCII) 

S - Set block for display or change 

/ - Display block ^ 

. - Change bytes in block 

T - Trace paragraphs 

L - Write CR,LF 

M - Define a debug macro 

$ - End a macro definition 

C - Display a specified character 

; - precedes a comment (for describing macros) 



The interactive debugger can be used on any 
COBOL program by including +D on the com- 
mand line that invokes the program, e.g.. 
■;*jnC +D test. int. This means that you can 
use the debugger on a program without hav- 
ing to do anything special when you compile 
it . 

Microware has Included eight subrou- 
tines in the COBOL run time system which 
can be called from a COBOL program. 
MOVE-BLOCK is a procedure that can be used 
to do a high speed move of a block of data. 
ABORT terminates the program with an error 
code. CHAIN makes the standard OS-9 F$Chain 
system call available. The FUN-KEY subrou- 
tine can be used after a ACCEPT statement 
to find out if a function key was pressed 
instead of the carriage return key, and 
which one. DATE returns the date and, 
optionally, the time. SHELL invokes a 
^hell, passing it a specified string. CHX 
d CHD change the execution and data 
^-rectories for the program. 



The Nucleus 

Table Handl ing 

Sequential Input and Output 

Relative Input and Output 

Indexed Input and Output 

Segmentation 

Library (Copy) 

Inter-program communication 

debug 



CIS COBOL supports parts of level 2 of ANSI COBOL 
including: 

• Nested IF 
PERFORM UNTIL 

• The START statement for Relative and 
Indexed I/O 

• Full level 2 Inter-program communica- 
t ion 



The subroutines in the run time system 
are called by number. CIS COBOL can also 
call subroutines which are either COBOL 
I -code, or object code. The CALL statement 

looks 1 ike: 

CALL *7D0/SUBLIB/TEST.SUB.r' 
USING . . . 

ON OVERFLOW 

The called program is loaded into memory if 
•t is not already there, and, depending on 
whether the module header indicates that it 
is I -code or object code, interpreted or 
executed. If there Is no room in memory 
for the new module, the ON OVERFLOW clause 
in the CALL statement gets control . The 
CANCEL verb unlinks a subroutine, freeing 
the memory it is using. 

In addition to these methods of calling 
external subroutines, CIS COBOL supports 
program segmentation, which can be used to 
divide the program Into sections that will 
remain on disk until they are needed. Seg- 
ments use memory efficiently at the cost of 
extra disk I/O by sharing a common pool of 
overlay memory. 

In addition to supporting ANSI COBOL 
level 1 , incl udi ng: 



LIMITATIONS 

I was disappointed with some of the 
restrictions of the low level of COBOL 
implemented for CIS COBOL, but not very 
surprised. I am more upset by some prob- 
lems with terminal support, and the CONFIG 
utility that is used to customize the run 
time package for a particular type of ter- 
minal . 

The features of advanced levels of 
COBOL that I missed most were AND and OR in 
IF statements. It is possible to do with- 
out boolean operations in IF statements, 
but I am not used to having to work around 
a limitation like that. Another very popu- 
lar feature which is missing in CIS COBOL 
is the SORT statement. A surprising number 
of production COBOL programs include at 
least one sort, and it would be hard to 
eliminate a sort from a program without a 
major redesign. 

The run time system which interprets 
the COBOL intermediate code also includes 
routines for terminal control . It is cus- 
tomized for a terminal by a utility program 
called CONFIG. I was not impressed with 
CONFIG. My favorite terminal uses the ANSI 
standard terminal control sequences 
CONFIG was clearly not written with my ter- 
minal in mind. I struggled for two eve- 
nings trying to get RunC configured for my 
TeleVideo with no success. Finally, I gave 
up and turned to my H-19, which was much 
more like what CONFIG wanted ... I had 
COBOL running in ten minutes. There were 
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three fundamental problems with CONFIG's 
handling of my TeleVideo's control sequenc- 
es. CONFIG expected most terminal control 
strings to be no more than three characters 
long; several of the ANSI strings are long- 
er than that. CONFIG simply can't deal 
with the ANSI direct cursor positioning 
sequence; I circumvented that problem by 
pretending that my terminal didn't have a 
direct cursor positioning command, and 
specifying relative positioning. CONFIG 
can only deal with commands that move the 
cursor one row or column at a time in rela- 
tive positioning mode. Since the ANSI 
strings that cause the cursor to move one 
row or column are three characters long, 
this is a slow way to adjust the cursor 
position. The clear-screen sequence for my 
terminal is four characters long; so I 
couldn't use it. RunC tries to fake a 
clear-screen somehow, but it makes a real 
mess of it. The clear-screen sequence 
somehow came out as a string of thousands 
of <bell> characters. I understand that a 
more recent version of CONFIG than the one 
I have allows a four character string for 
the clear-screen sequence. I think that 
would have made it possible for me to get 
my TeleVideo working with COBOL. 

CONFIG forms a trap for the unwary 
user. Once you start into it there is no 
turning back. If you change your mind 
about the response you just keyed in, you 
have to wait until you reach the end of the 
entire (long) string of questions, and ask 
to be allowed to change a large subset of 
your answers. When you are going through 
CONFIG to fix a mistake or change an exist- 
ing terminal description to fit a new ter- 
minal, you have to fill in the correct 
answer to each question. There is no way 
to select a default, or keep the old value. 
It is true that CONFIG is not likely to be 
a heavily used utility, but I found it so 
hard to use that I would much rather have 
written a few subroutines to support my 
terminal s . 

Once I got the screen support working, 
I found that I wasn't pleased with the way 
it worked. I believe that when the cursor 
leaves a numeric field, the field should be 
right justified and zero filled. The 
screen handling package in CIS COBOL seems 
to agree with me to some extent. If you 
enter a "." in an integer field it will 
right justify and zero fill, but if you 
exit the field with a carriage return (end- 
ing the entire screen) or down arrow (mov- 
ing to the next field), a test for numeric 
in the program will indicate that the field 
IS not numeric. If the field has editing 
char-acters in it the field is inclined to 
end up left justified and zero filled. 

I am used to getting useful, english 
error messages from COBOL; CIS COBOL gives 
error messages with numeric codes in them 
indicating what the error is. Even after I 
looked up the error, it wasn't clear what 
the problem was. For instance, when I 
hadn't declared a variable it told me that 
there was a type mismatch in the statement 
using the undeclared variable. When I 
tried to use AND and OR, it gave me the 
same error. I ended up treating the error 
message as "something's wrong around here." 



BENCHMARKS 

I ran two benchmarks against this COBOL: 
one for speed at numeric processing (the 
sieve), the other for speed in handling 
ISAM files. I adjusted the prime number 
program from the January 1983 BYTE slightly 
to fit ANSI level one, and ran it. This 
version of COBOL would have fallen nearly 
at the bottom of the chart given in that 
BYTE, between Microsoft COBOL and RMCOBOL . 
It took 54 1 seconds to find the first 1899 
primes. I could have made the program run 
somewhat faster by using indexing instead 
of subscripting. but that would have 
spoiled the benchmark. I have to admit 
that I felt silly writing a Eratosthenes 
Sieve program in COBOL. Testing COBOL for 
its ability to find prime numbers is like 
testing programmers for their ability to 
read Latin; they may be able to do it but 
1t is hardly relevant. I ran that bench- 
mark because it is the most used benchmark 
for microcomputer languages, but I also ran 
another non-standard, but, I think, more 
relevant, benchmark. 

I constructed a benchmark program which 
gives a good measure of the speed with 
which the language handles indexed I/O. 
Indexed I/O is very important to the group 
of users who might use COBOL. Interpreting 
the results of a benchmark that involves 
I/O is a little tricky. Certainly the file 
structure the language uses is very impor- 
tant, especially with a large indexed file; 
but the access time for the disk is an 
important factor, and the time the operat- 
ing system takes for a context switch is 
somewhat important. 

I built a file 10.000 records long of 
55 byte records with five byte keys and 
then read it randomly reading two records 
alternately from each end. It took 2615 
seconds to build the file and 3233 seconds 
to read the file (it would, of course, have 
been possible to read it faster if I had 
read sequentially). I ran these benchmarks 
on a GIMIX system with a CM 5000 Winchester 
(a file that size would not have fit on my 
8" floppies). I used OS-9 Level Two on a 2 
mhz 6809. The performance would have been 
much worse if I had used a floppy instead 
of a Winchester, and somewhat better if I 
had used GMX-III . 

I compiled three COBOL programs on the 
same machine I ran the benchmarks on. A 
simple merge program which I haven't 
included with this review took 45 seconds 
to compile, the sieve compiled in 35 sec- 
onds, and the ISAM test program took 43 
seconds . 



SUMMARY 

It is possible to get past the problems 
with CONFIG, to learn to live with the 
primitive error messages, and to feel com- 
fortable with the screen handling conven- 
tions. What is left is a substantial 
implementation of an old, but useful lan- 
guage. I don't think everyone should run 
out and buy this package, but, for a few 
people, it could be uniquely useful. If 
you want to use a group of COBOL programs 
on microcomputer, it would certainly be 
easier to convert them from one level of 
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COBOL to another than to translate them 
into an entirely different language. CIS 
COBOL would be a good teaching tool for 
schools unable to afford time on a machine 
with a full-blown COBOL compiler. It 
should be relatively easy to find program- 
mers who can work in COBOL. With CIS 
COBOL, a microcomputer could be used as a 
development environment for COBOL programs, 
though the low level of CIS COBOL would 
prevent this in most cases. Perhaps the 
most significant advantage of CIS COBOL 
over other languages is that programs writ- 
ten in CIS COBOL can be moved in I -Code 
form to a variety of other machines and 
operating systems, and run without source 
code. UCSD Pascal has shown that this is 
an asset even though it can't generally run 
under a normal operating system. 

CIS COBOL was written by Micro Focus 
Limited. Microware wrote a run time pack- 
age for it that allows any program written 
in CIS COBOL, including CIS COBOL itself. 



to be run under 05-9. By writing a run 
time package for CIS COBOL, and arranging 
to license it for OS-9, Microware made a 
large collection of business software 
available to OS-9 users. If you are look- 
ing for a nice accounting system, payroll. 
MRP system, or whatever, check with Micro- 
ware. They have a long list of vendors 
offering programs which run under the CIS 
COBOL run time system. 

Some small number of people will find 
Microware's version of CIS COBOL just what 
they need. If you think you are one of 
those people, I recommend that you get the 
manual before you commit to the language. 
The manuals won't be any help to you if you 
don't know COBOL, but. if you do, they will 
leave you with an accurate impression of 
the language, and either leave you impa- 
tient to get the software, or disappointed 
about some important missing feature (most 
1 ikely sort ) . 



COBOL TEST PROGRAM 

*'^ CIS COBOL V4,4 



Test.CBL 



PAGE: 0001 



IDENTIFICATION DIVISION. 
PROGRAM- ID, FIRST-TEST, PROGRAM. 
AUTHOR. PETER DIBBLE, 
ENVIRONMENT DIVISION, 
CONFIGURATION SECTION, 
SOURCE-COMPUTER. GIMIX, 
OBJECT-COMPUTER. GIMIX. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL, 

SELECT INPUT-1 ASSIGN ":CI:" 

ORGANIZATION IS LINE SEQUENTIAL. 
SELECT MERGE-FILE ASSIGN MERGE-NAME. 
SELECT TEMP-FILE ASSIGN "MERGE. TEMP*', 
DATA DIVISION. 
FILE SECTION. 
FD INPUT-1; 

RECORD 40; 
BLOCK 5; 

LABEL RECORDS ARE STANDARD, 
INPUT-1-LINE 
MERGE-FILE; 
RECORD 20; 
BLOCK 10; 

LABEL RECORDS ARE STANDARD. 
MERGE-LINE 
TEMP- FILE: 
RECORD 20; 
BLOCK 10; 

LABEL RECORDS ARE STANDARD. 
TEMP-LINE 
WORKING-STORAGE SECTION. 
01 IN-THIS 

LINE-FMT REDEFINES IN-THIS, 
02 KEEP-THIS. 
04 FILLER 
04 CARRIAGE-RETURN 
02 FILLER 
MERGE-THIS 
FILE- STAT 
PROCEDURE DIVISION, 
START-UP , 
* PARAMETERS ARE GIVEN IN THE FIRST RECORD OF STD. 
OPEN INPUT INPUT-1, 
READ INPUT-1 INTO MERGE-NAME, 
OPEN INPUT MERGE-FILE, 
OPEN OUTPUT TEMP-FILE, 
DISPLAY "MERGING STANDARD INPUT WITH ", MERGE-NAME 



01 
FD 



01 
FD 



01 



01 



01 
01 



PIC X(40) 



PIC X(20) 



PIC X(20). 

PIC X(40) VALUE SPACES. 



PIC X(19), 

PIC X. 
PIC X(20), 

PIC X(20) VALUE SPACES, 
PIC X VALUE "0". 



INPUT 
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^^' CIS COBOL VA.4 Test.CBL PAGE: 0002 

READ INPUT- 1 INTO IN-THIS; 

AT END MOVE HIGH-VALUES TO IN-THIS. 
PERFORM FIX-IN. 
READ MERGE-FILE INTO MERGE-THIS; 

AT END MOVE HIGH- VALUES TO MERGE-THIS. 
MAIN-SECTION. 

PERFORM MERGE-LOOP UNTIL FILE-STAT EQUAL TO »'1'\ 
MOVE "0*' TO FILE-STAT. 
CLOSE MERGE-FILE. 
OPEN OUTPUT MERGE-FILE. 
CLOSE TEMP-FILE. 
OPEN INPUT TEMP-FILE. 
PERFORM READ- TEMP. 

PERFORM COPY-TEMP-TO-MERGE UNTIL FILE-STAT EQUAL TO "T*. 
STOP RUN. 
MERGE-LOOP. 

PERFORM PICK-NEXT. 
WRITE TEMP-LINE. 
END-MERGE-LOOP. 

EXIT. 
PICK-NEXT. 

IF KEEP-THIS < MERGE-THIS 
THEN 

PERFORM FIX- IN 
MOVE KEEP-THIS TO TEHP-LINE 
READ INPUT- 1 INTO IN-THIS; 
AT END PERFORM END- IN 
ELSE 

MOVE MERGE-THIS TO TEMP-LINE 
READ MERGE-FILE INTO MERGE-THIS; 
AT END PERFORM END-MERGE. 
PICK-NEXT-END. 

EXIT. 
END- IN. 

MOVE HIGH-VALUES TO IN-THIS. 
IF MERGE-THIS - HIGH-VALUES 
THEN 

MOVE "!*' TO FILE-STAT. 
END-MERGE, 

MOVE HIGH-VALUES TO MERGE-THIS. 
IF IN-THIS - HIGH-VALUES 
THEN 

MOVE "1" TO FILE-STAT. 
FIX-IN. 

MOVE X"OD" TO CARRIAGE-RETURN. 
COPY-TEMP-TO-MERGE. 

WRITE MERGE-LINE. 
PERFORM READ-TEMP. 
END-COPY-TEMP-TO-MERGE. 

EXIT. 
READ- TEMP. 

READ TEMP-FILE; AT END PERFORM END- TEMP. 
MOVE TEMP-LINE TO MERGE-LINE. 
END-READ-TEMP. 

EXIT. 
END-TEMP . 

MOVE "1" TO FILE-STAT. 
END- INPUT. 

MOVE HIGH-VALUES TO IN-THIS. 
END-MERGE- IN. 

MOVE HIGH-VALUES TO MERGE-THIS. 
END-PROGRAM. 
EXIT. 
** CIS COBOL VA. 4 'REVISION URN rp/ 

** COMPILER COPYRIGHT (C) 1978,1981 MICRO FOCUS LTD 
*''^ ERRORS«00000 DATA«00791 CODE=00489 DICT-00654:01229/01883 GSA FLAG 



Review of OS-9 CIS COBOL 127 



COBOL SIEVE 

-' CIS COBOL V4.A 



siev.cbl 



PAGE: 0001 



IDENTIFICATION DIVISION. 

PROGRAM-ID. SIEVE. 

AUTHOR. PETER DIBBLE, 

ENVIRONMENT DIVISION. 

WORKING-STORAGE SECTION. 

77 PRIME PIC 9(5) COMP. 

77 PRIME-COUNT PIC 9(5) COMP. 

77 I PIC 9(4) COMP. 

77 K PIC 9(5) COMP. 

01 BIT- ARRAY. 

03 BIT OCCURS 8191 TIMES PIC 9 COMP. 
PROCEDURE DIVISION. 
START-UP. 

DISPLAY "TEN ITERATIONS". 

PERFORM SIEVE THROUGH SIEVE-END. 

DISPLAY "PRIMES FOUND: ", PRIME-COUNT. 

STOP RUN. 
SIEVE. 

MOVE ZERO TO PRIME-COUNT. 

MOVE 1 TO I. 

PERFORM INIT-BITS 8191 TIMES. 

MOVE 1 TO I. 

PERFORM SCAN-FOR-PRIMES THROUGH END-SCAN-FOR- PRIMES 
8191 TIMES. 
SI EVE" END. 

EXIT 
INIT-BITS. 

MOVE 1 TO BIT (I) , 

ADD 1 TO I. 
END- INIT-BITS. 

EXIT. 
SCAN-FOR-PRIMES. 

IF BIT (I) - 
THEN 

GO TO NOT-PRIME. 

AI^ I I 1 GIVING PRIME. 
DISPLAY PRIME. 

ADD I PRIME GIVING K. 

PERFORM STRIKOUT UNTIL K > 8191. 

ADD 1 TO PRIME-COUNT. 
NOT-PRIME. 

ADD- 1 TO I, 
ENIV SCAN-FOR-PRIMES . 

EXIT 
STRIKOUT. 

MOVE TO BIT (K) . 

ADD PRIME TO K. 
END-PROGRAM. 

EXIT. 
*'' CIS COBOi VA. 4 'revision 



^ 



URN rp/ 
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COBOL BENCHMARK PROGRAM 

** CIS COBOL VA.4 



Bnch.CBL 



PAGE: 0001 



IDENTIFICATION DIVISION. 
PROGRAM- ID. ISAM-BENCHMARK 
AUTHOR. PETER DIBBLE. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. GIMIX. 
OBJECT-COMPUTER. GIMIX. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT ISAM-FILE-1 ASSIGN "ISAM. FILE"; 
ORGANIZATION IS INDEXED; 
ACCESS MODE IS SEQUENTIAL; 
RECORD KEY IS ISAM-KEY-1. 

SELECT ISAM-FILE-2 ASSIGN "ISAM. FILE"; 
ORGANIZATION IS INDEXED; 
ACCESS MODE IS RANDOM; 
RECORD KEY IS ISAM-KEY-2. 
DATA DIVISION. 
FILE SECTION. 
FD ISAM-FILE-1 ; 

DATA RECORD I SAM-RECORD* 1 . 
01 ISAM-RECORD- 1. 

03 ISAM-KEY-1 

03 FILLER 
FD ISAM-FILE-2; 

DATA RECORD I SAM-RECORD- 2 
01 ISAM-RECORD-2. 

03 ISAM-KEY-2 

03 FILLER 
WORKING-STORAGE SECTION. 
77 KEY-NO 



PIC 9(9) COMP- 
PIC X(50). 



PIC 9(9) COMP-3. 
PIC X(50) . 



PIC 9(9 
PIC 9(9 
PIC 9(9> 
PIC XXX 



COMP-3 VALUE 0. 

COMP-3. 

COMP-3. 

VALUE "004". 



(9) C 
(50). 



COMP-3. 



77 HI -NUMBER 
77 LO-NUMBER 
77 DATE 
01 WORK-DATA. 

03 WORK-KEY PIC 9 

03 I-DATA PIC X 

01 SYSTEM-DATE. 

03 YEAR PIC 99. 

03 MONTH PIC 99. 

03 DAY PIC 99. 

01 SYSTEM-TIME. 

03 HOUR PIC 99. 

03 MINUTE PIC 99. 

03 SECOND PIC 99. 

PROCEDURE DIVISION. 
START-UP . 

OPEN OUTPUT ISAM-FILE-1. 

MOVE "ASSORTED DATA: NAME, ADDRESS, ETC, OR WHATEVER" TO 
I-DATA. 

ADD 1 KEY-NO GIVING LO-NUMBER. 

MOVE KEY-NO TO WORK-KEY. 

DISPLAY "START BUILD". 

CALL DATE USING SYSTEM-DATE, SYSTEM-TIME. 

DISPLAY "TIME " HOUR, ":", MINUTE, ":", SECOND 
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'^" CIS COBOL VA.A Bnch.CBL PAGE: 0002 

PERFORM ADD-RECORD 10000 TIMES. 

CLOSE ISAM-FILE-1 

DISPLAY "BUILD DONE". 

CALL DATE USING SYSTEM-DATE, SYSTEM-TIME. 

DISPLAY "TIME " HOUR, ":", MINUTE, ":", SECOND 

MOVE WORK-KEY TO HI -NUMBER. 

DISPLAY "READ STARTING". 

OPEN INPUT ISAM-FILE-2. 

PERFORM TEST-READS 2500 TIMES. 

CLOSE ISAM-FILE-2. 

CALL DATE USING SYSTEM-DATE, SYSTEM-TIME. 

DISPLAY "TIME *' HOUR, ":", MINUTE, ":", SECOND 

DISPLAY "READ DONE". 

STOP RUN. 
ADD-RECORD. 

ADD 1 TO WORK-KEY. 

WRITE I SAM-RECORD- 1 FROM WORK-DATA; 
INVALID KEY PERFORM ERROR- 1. 
ERROR- 1. 

DISPLAY "INVALID KEY: ", ISAM-KEY-1. 
TEST-READS. 

PERFORM READ-HIGH. 

PERFORM READ-HIGH. 

PERFORM READ- LOW. 

PERFORM READ-LOW* 
READ-HIGH. 

MOVE HI-NUMBER TO ISAM-KEY-2, WORK-REY. 

READ ISAM-FILE-2; INVALID KEY PERFORM ERROR-2. 

SUBTRACT 1 FROM WORK-KEY GIVING HI-NUMBER. 
ERROR-2. 

DISPLAY "INVALID KEY: ", WORK-KEY. 
READ- LOW. 

MOVE LO-NUMBER TO WORK-KEY, ISAM-KEY-2. 

READ ISAM-FILE-2; INVALID KEY PERFORM ERROR-2. 

ADD 1 WORK-KEY GIVING LO-NUMBER. 
END-PROGRAM. 

EXIT. 
^'- CIS COBOL V4. 4 'revision URN rp/ 

-'^ COMPILER COPYRIGHT (C) 1978,1981 MICRO FOCUS LTD 
'^" ERRORS-OOOOO DATA«00705 CODE«00703 DICT=00612:01271/01883 GSA FLAG 
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REVIEW OF SOFTWARE BY 
CLEARBROOK SOFTWARE GROUP 



DEDIT 



Overview 

DEdit is a screen-oriented editor which is 
intended for use on non-text files. It 
displays the contents of a file (or an 
entire disk) in what amounts to "dump" for- 
mat for inspection and modification. I 
think it should be possible to configure 
DEdit for any terminal that has direct cur- 
sor positioning support. 



The three main uses I would have for 
this kind of editor are placing special 
characters in text files, fussing with 
directories (unerasing files), and zapping 
modules. For zapping text f i les it would 
be nice to be able to eliminate the hex 
window for quick scanning of a file. Per- 
haps a one byte hex window could be kept at 
the top of the screen the way the binary 
window is. Fussing with directories would 
be much easier if the editor would format 
the directory in a meaningful way -- the 
format is right there in the System Pro- 
grammer's Manual, but I appreciate programs 
that make things easier for me. The module 
format is another one that could be dis- 
played more meaningfully. The module header 
could be separated from the rest of the 
module and the parts of it labeled. Disas- 
sembled format would be another nice fea- 
ture. 



Details 

DEdit is a minimal, but adequate, editor. 
It has a set of 16 one-keystroke commands 
consisting of five cursor control keys 
(up. down, left . right , and home), eight edi- 
tor control keys (exit, reread sector, next 
sector, previous sector, write sector, and 
read specified sector), three keys to con- 
trol a "find" facility (find, again, and 
abort find). The remaining two commands 
control the edit "windows." 

DEdit can display either two or three 
windows at a time. The main window is a 
hexadecimal format display of a sector of 
the file being edited. To the right of the 
hexadecimal display is an ASCII display of 
the printable characters in the sector. The 
third window, positioned near the top of 
the screen, is the binary representation of 
the character which the cursor is posi- 
tioned to. There is a command to move the 
cursor from window to window, and a command 
to turn the binary window on and off. 

The characters corresponding to the 16 
commands are specified by a table in the 
DEdit program who's location is given in 
the documentation. I found the choice of 
command characters strange, and promptly 
changed them to something I could remember; 
it was fairly easy to change the table with 
debug (I could have used DEdit). 

Another table in the DEdit program 
describes the characteristics of your ter- 
minal . DEdit is supplied configured for the 
TVI 910, but can be altered to work with 
most other terminals. The terminal must 
support direct cursor positioning, and a 
clear screen/home cursor sequence that is 
no more than four bytes long. 



Limitations 

There are no serious drawbacks to 
DEdit. It works reliably, and has enough 
features to be useful. DEdit seems to have 
been designed to be used for emergency 
repairs to directories, and other special 
purposes. This kind of use doesn't call for 
a feature packed editor; still, I am disap- 
pointed in the bare-bones approach Clear- 
brook took to this problem. 



Even a Dare-bones editor needs a good 
manual. DEdit's manual is not good. For 
anyone but a brave and experienced hacker 
the poor documentation could entirely rule 
out use of this program. The commands are 
all described on one page together with 
directions for changing the command charac- 
ters. The terminal description table is 
described in two and a half pages in suffi- 
cient detail that any experienced assembly 
language programmer should be able to con- 
figure the program for a terminal ... 
eventually. I spent quite a while learning 
that the numeric fields were unsigned. 
Despite the fact that one- byte fields are 
almost always signed in 6809 machine lan- 
guage, the unsigned nature of these fields 
was never mentioned. Perhaps it should have 
been obvious to me (after all, cursor posi- 
tions are never negative), but I used about 
ten minutes figuring this out. 



Summary 



For someone who needs a disk editor right 
now, DEdit would be a useful utility. For 
anyone who can wait, I would recommend 
hanging on; this program has more features 
than the various free ones I know of, but 
not enough to make i t worth the money to 
someone who will only use it occasionally. 



BT9 



Overview 

BT9 is a module which maintains files in a 
binary tree format. The BT9 module can be 
celled from BasicOS, or any other language 
which can use the BasicOS calling sequence. 



Details 



Fourteen commands can be passed to BT9 
al 'owing random access, and sequential 
access (forward or backwards) to files 
built and maintained through BT9 . The com- 
mands are: 
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_ 


Read file header 




(done after open) 


- 


Write file header 




(done before close) 


1 "■ 


Read a record 


t ^ 


Write a record 


- 


Add a record 


- 


Quick add 


- 


Update current record 


- 


Delete current record 


- 


Find = key 


- 


Find >« key 


- 


Find record with lowest key 


- 


Find record with highest key 


- 


Find next higher record 


- 


Find next lower record 



The documentation is marginal, but there is 
a demonstration program which is a great 
help . 



Limitations 

There is a tremendous problem with this 
program. They picked the wrong file struc- 
ture. A binary tree isn't even the data 
structure of choice for use in high speed 
memory when the data is not static. A plain 
binary tree like what BT9 uses will struc- 
ture data in the worst possible way when 
the data is added in sorted order. On disk 
the idea of a binary tree is just horrify- 
ing . 

Trees from a family called bichromatic 
trees have the characteristic that they 
don't grow long branches causing poor per- 
formance. Most data structures texts 
include AVL trees and 2-3 trees from this 
family. The mos't popular, and probably the 
best, type of tree to use on disks is the 
B-tree. A B-tree is something like a binary 
tree, but it doesn't have nasty habits like 
the binary tree, and it is much faster than 
the binary tree when the data is on disk. 

After accusing this program of using 
the wrong data structure it hardly seems 
reasonable to bother with any other prob- 
lems, but there is one other major problem 
that would be a good deal easier to fix. 
BT9 takes a rather casual attitude toward 
disk errors. They are reported to the user, 
Dut not reflected to the calling program in 
any way. This sloppy treatment of errors 
makes it impossible for a program to 
attempt any form of automatic recovery from 
disk errors. 



Summary 

can only imagine using this module to 
£:/lve a problem in a quick and dirty way. 
It would not be very difficult to write a 
module which was upwardly compatible with 
this one but used a B-tree data structure. 



D-SERIES UTILITIES — DDIR, 
DDEL, DCOPy AND DATTR 



Overview 

I bet every DS-9 user has been waiting for 
these programs. They are generalizations on 
the DIR, DEL, COPY, and ATTR commands which 
work on multiple files. 



Details 



Since this review was written Clearbrook 
has announced a package that supports 
B-Trees . 
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All the D-Series command include a <file 
speo option as one of the parameters. The 
<file speo can include part of a file 
name, an attribute of the file (ie D S PR 
PW PE R W and E), a user number, or to 
indicate the user's own files. These can be 
combined with AND, OR, NOT and parenthesis. 
The <file spec> is used by the D-Ser1es 
commands to select the files which will be 
acted on. 

The DDIR command gives a simple (one 
column) list of all the files which meet 
the selection criteria in a specified 
directory and, optionally, in lower level 
directories. The output of of DDIR is for- 
matted by indenting for each level into the 
directories which makes it quite readable. 

The DDel command deletes all the files 
meeting the selection criteria. It can 
optionally prompt before deleting each 
file, list the files as tney are deleted, 
and search the specified directory and all 
lower level directories. 

The DAttr can change the attributes and 
owner of files meeting the selection cri- 
teria. The options are the same as for DDel 
with the addition of a set of options to 
specify the new file attributes and owner. 
Only a superuser (user 0) can change the 
owner of files he doesn't own. 

The DCopy command copies all files 
meeting the selection criteria from a 
selected directory to another selected 
directed. The options are: 



prompt before copying 

list files as they are copied 

copy files in specified and lower 
di rectories 

make directories 

delete files which already exist in 
destination directory 

Problems and Limitations 

The file selection criteria used with these 
commands are not as elaborate as the cri- 
teria the equivalent UNIX commands use. In 
particular there are no wild cards or pat- 
tern metching options. 

If any command line parameters are 
specified for the DDir, DDel, and DAttr 
commands the directory name must be includ- 
ed on the command line. Most OS-9 commands 



use "." as the default directory, and the 
D-Series commands do if no parameters are 
given. It seems inconsistent that they 
don't always allow the directory to be 
def aul ted . 

The DDIR command somet imeSgreturns with 
an error 211 (end of file). It is my 
theory that this is returned from the last 
read of the directory, and is entirely 
innocent, but shouldn't be returned to the 
shel 1 . 

minor complaint about the documenta- 
tion: every time "pr pw" should have been 
in the documentation, "pr pr" was there 
instead. 



Summary 

The D-Series commands are very useful. They 
are not without faults, but, especially for 
systems with large capacity disks (lots of 
files), they are almost essential. 



Reconsideration 

I sent this review to Clearbrook Software 
Group for their comments. They returned 
the letter which I have included with this 
review, revisions to the documentation for 
the editor, a new edktor, and a config 
program for the editor. 

The documentation is much improved, 
although it still suffers from having been 
written by a knowledgeable person. They 
include directions for recovering a deleted 
file which are useful, and what appears to 
be a screen dump of a dedit screen which is 
also nice to have. With the original docu- 
mentation, I spent a while trying to use 
DEdit before I realized that I had it con- 
figured wrong. 

I had trouble with the "conf ig_dedi t " 
program they sent me; it sometimes just 
stopped. It was a packed Basic09 program 
so I couldn't tell whether it was an incom- 
patibility with my BasicOS, or something 
el se . 

The new version of DEdit is identical 
to the one I already had. I ran the OS-9 
compare utility, cmp, against them and 
found they only differed in the bytes that 
are changed when the terminal configuration 
is done. 

The improvements to the documentation 
are nice, and the configuration program 
seems like it might make it a good deal 
easier to set DEdit up for a terminal, if 
it would work. 



This problem (error 211) has since been 
f ixed 

The letter isn't included here, but it 
detailed the improvements they had made, 
and said that DEDIT did what it was 
intended to do very nicely. 
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A REVIEW OF DYNACALC FOR 
OS-9 



OVERVIEW 

DYNACALC is a very capable electronic 
spread sheet program. It is enough like all 
the other spread sheet programs (visi- 
clones) so anyone familiar with one of them 
should be able to adjust to DYNACALC very 
quickly. DYNACALC is not a great leap 
beyond all other electronic spread sheets, 
but it is a very good example of the cur- 
rent state of the art. 

A electronic spread sheet program makes 
the terminal appear to be looking at a sec- 
tion of a large grid. The "cells" in the 
grid can each contain a number, equation, 
or character string. The equations usually 
operate on the contents of other cells (A 
column of cells might contain monthly 
expenses*, and another eel 1 somewhere on the 
grid might contain the sum of all the cells 
in the column of expenses.) The special 
thing about electronic spread sheets as 
opposed to paper spread sheets is that when 
a number or equation on an electronic 
spread sheet is changed, all the cells that 
depend on that value are updated to reflect 
the change. This is a simple idea, but such 
a good idea that I know of many people who 
have purchased computers just to be get at 
this kind of program. 



SOME DETAILS 

DYNACALC is a large 6803 assembly language 
program which has beerf available under FLEX 
since last year. It is now also available 
under OS-9. The DS-9 version doesn't seem 
like warmed over FLEX code; it seems to 
have been designed for 05-9. It is reent- 
rant (the same module can be used by any 
number of simultaneous users), and uses 
standard input and output. Practically any 
CRT type terminal can be supported. In 
fact, the warranty for DYNACALC says that 
if you have a CRT terminal with at least 80 
characters per line and direct cursor 
addressing: 

If your terminal has the 
required characteristics, but 
you are unable to configure 



DYNACALC to work properly 
(using the INSTALL utility), 
send us your original DYNACALC 
diskette and a copy of the 
operator's manual for your 
CRT. We will either make it 
work on your terminal, at no 
extra charge to you, or refund 
your full DYNACALC purchase 
price. 

That is a very impressive commitment! If 
you have several users on your system with 
different types of terminal, you can get 
DYNACALC to support them all concurrently 
if you have each terminal type use a dif- 
ferent data directory, and put the appro- 
priate terminal file in each directory. 

DYNACALC can save the contents of a 
spread sheet in a file that can be read by 
other programs, I wouldn't call the files 
easy to use, but they aren't impossible to 
use either, and the format is clearly docu- 
mented. DYNACALC s saved data is hard to 
use because the format of the file reflects 
DYNACALC's flexible attitude towards the 
user - it will take any sort of data scat- 
tered around anywhere you like. If you want 
to create a file for DYNACALC to use as 
data for a spread sheet, you don't have to 
cope with the vicissitudes of humans. It is 
a relatively simple job to create data 
files for DYNACALC. 

An excellent help facility is an inte- 
gral part of the program, though you can 
remove it to save space if you want. Most 
of the time you can type a "?" to access a 
screen of terse explanations of your 
options. The help screens do not take the 
place of reading the manual, but they can 
provide a quick jog of the memory. There 
are also 12 error codes which I wish all 
vi sic! ones had. Spread sheets can take on 
some of the attributes of complicated pro- 
grams, especially hard to find bugs. Imag- 
ine trying to debug a program with only one 
error message like "Sorry, I can't do 
that," "Say Wha?" or whatever. 

My copy of DYNACALC came the terminal 
files listed in Figure 7, I recognize 
SWTPC, Hazeltine, Adds, Heathk i t/2eni th, 
ADM, and Televideo in there. Even if your 
terminal isn't in that list, you can use 
the INSTALL. DC utility to build a terminal 
file for your terminal. 



ct 82 
c82 w 
h_1500 
act iv 
pe_550 

Figure 7: 



Ct 82 92 
c82__w-92 
adds vpt 
adm 3a 
info 100 



c8200 
h 1400 
a3ds_3a 

ansi 
iq_120 



c8200 92 
h 1A2D 
h-19 
tv 912 
tv"950 



Dynacalc Terminal Support 



A particularly strong point of DYNACALC 
is the set of powerful functions it sup- 
ports, including basic math (trig, log/exp, 
square root, max/min, pi, int. round, and 
absolute value), "group" functions (sum, 
average, standard deviation, net present 
value, choose, lookup, and index), and a 
bunch of miscellaneous functions. Choose 
selects the nth entry from a list, lookup 
is the standard visiclone lookup function, 



and index is like lookup except that it 
scans for an exact match instead of greater 
than. Many of DYNACALC's functions work 
witn either character strings or numbers. 
This expands the usefulness of the func- 
, tions substantially. 

^ DYNACALC has commands which move rows 
^^ and columns around. and do insert and 
.. delete operations on them. The fanciest 
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command in this family is the sort command, 
which allows you to sort rows or columns 
dased on the values in a column or row 
respect i vel y . 

I have never been entirely pleased with 
c^^e speed of any program. Of course I wish 
DYNACALC ran faster, but I don't remember 
using a spread sheet program on a microcom- 
puter that ran faster. 



LIMITATIONS AND PROBLEMS 

The only real problem with DYNACALC is with 
its terminal support, and I'm not sure it 
could have been done much better without 
losing generality. The terminal support 
problem is not a major one. In fact. I 
imagine that after a few months of using 
the program I will feel nothing but affec- 
t ion for i t . 

It is hard to choose characters to use 
as arrow keys. DYNACALC uses curly and 
?^quare brackets as cursor control keys by 
default. This is a good choice if you want 
to drive it with a disk file, but not very 
intuitive. If you like this choice as lit- 
tle as I did you can change it with 
INSTALL. Unfortunately install only allows 
you to use single characters as control 
keys; my terminal, like most terminals, 
sends escape sequences when the arrow keys 
are pressed. 

Screen updating is not as fast and 
smooth as it is on machines that have inte- 
gral screen support. I^ understand that a 
9600 baud terminal can't possibly compete 
with memory mapped video, but I believe 
that, if the insert and delete character 
and line facilities on my terminal were 
used, the screen could be updated more 



quickly. It would have been hard to make 
DYNACALC support more advanced terminals 
while still supporting "dumb" terminals, 
but I wish it had been done. 



SUMMARY 

DYNACALC is a fine program, but although it 
seems to have been written by a programmer 
familiar with OS-9, it doesn't make the 
fullest use of the power of OS-9. I wish 
DYNACALC could use all available memory 
instead of just 64K, and I wish printing 
was handled by a separate process so I 
could start a copy of a sheet printing, 
then continue work on the original. Extend- 
ed memory probably could have been used 
under Level Two without degrading the pro- 
gram under Level One, and multiple process- 
es are supported by both levels of OS-9. 

I find myself expecting a great deal of 
DYNACALC. My carping at its terminal sup- 
port (which is in many ways unusually 
good), and pushing for support of fancy 
OS-9 features is a reflection of my very 
high opinion of the program. 

I know people who find it reasonable to 
buy a personal computer just to have an 
electronic spread sheet, DYNACALC is an 
excellent spread sheet program. It can help 
with any number of business problems, sim- 
ple problems in the sciences, and just 
plain Showing off the computer to the unin- 
itiated. I think DYNACALC is a program 
which Should be included in the toolkit of 
most OS-9 users. One warning, spreadsheet 
programs tend to be popular. I am afraid 
that I will have to wait for a crack at my 
machine more often now that I have DYNACALC 
on 1 1 . 
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REVIEW OF DYNAMITE 



OVERVIEW 

Dynamite is a disassembler for the 
6809/6800 sold by Computer Systems Center. 
The version I tested runs under 05-9, but 
there are other versions for FLEX and Uni- 
FLEX. Disassemblers are able to convert a 
file of executable object (machine) code 
into a program in assembly language. It is 
important to realize that Dynamite won't 
work on intermediate code, such as Basic09 
packed files, and it won't always convert 
object files into the original language. 
Dynamite can convert an executable object 
module generated by any language into 
assembly language. Even if the program was 
written in a higher level language like 
Pascal or C, Dynamite will only produce 
assembler . 

If you have reliable software and don't 
like to dig around in your system much, you 
have no need for Dynamite. Don't waste 
your money. If you would like to fix (mod- 
ify) your software, or just want to under- 
stand it as only someone with the source 



code can, Dynamite, or some other disassem- 
bler, is valuable. I have disassembled 
many pages of code by hand. Those hours of 
work qualify me to say that disassembly is 
just the type of work which should be left 
to computers. 



SOME DETAILS 

Dynamite can be used to get a quick look at 
source that could have generated an object 
file. The command: 

DYNAMITE filename a 

will disassemble the module in the file 
called filename and send its output, which 
looks like the the output of an assembler, 
to the terminal. The "a" option tells 
Dynamite to give the asci i equivalent of 
each printable character it encounters dur- 
ing the disassembly. This simple disassem- 
bly is enough in many cases. If the module 
is more complicated than is easy to under- 
stand without meaningful labels, the next 
step is to help Dynamite do a better job of 
decoding the module until its output is 
understandabl e . 





Table 2: Dynamite Label Classes 


D 


Direct references 


L 


PCR references 


X 


Extended references 


$ 


Hex constant 


& 


Decimal constant 


(3 


Decimal or Hex constant depending on magnitude 


-n 


ASCII constant 


I 


System function name 



TabJe 3: Dynamite Addressing Modes 



#1 - one byte immediate (any register) 
//D - Immec* " '"" ' " " " ^ 

X,y,U,S - Indexed by X.Y,U, or SP 



#D - Immediate with Accumulator D 
»X,#Y.#U,#S 



Immediate with other registers 



D - Direct page 

£ * Extended addressing 

R - Relative 



Dynamite doesn't distinguish between 
data and instructions while disassembling. 
This results in some very strange output as 
blocks of constants are disassembled. Even 
the name of the program pointed to in the 
module header is decoded into assembly lan- 
guage instructions. The "a" option makes 
it easy to find the data areas, and Dyna- 
mite can be told where they are either 
through its standard input or in its com- 
mand file. Once Dynamite knows where the 
data areas are. it will stop disassembling 
them as instructions. Instead, it will 
label the entries in the data area, and 
disassemble them into constants 
(fob, fee, . . . ) . 

When Dynamite is run without any gui- 
dance, it invents names for everything it 
encounters that might have had a name in 
the original program. Addresses, offsets, 
and immediate data all are given names. 



Names for Immediate data and offsets are 
useful . Names for offsets in PCR instruc- 
tions are VERY useful because, although 
different references to a location will 
have different PCR offsets. Dynamite 
resolves them to the same name. 

An assembly language program more than 
about a page long is hard to read unless it 
has meaningful names. Dynamite gives names 
that consist of a letter and a number. 
More meaningful names can be assigned by 
using a 1 abel file. 

Dynamite can use two classes of files 
with label definitions in the form of 
equates. It always uses a "system name" 
file which contains the names used for each 
059 call. When the instruction: 



0S9 I$Open 
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is decoaed the "I$Open" comes from the sys- 
tem name file. The second file full of 
label definitions is the "label file." The 
label file's name has to be given in the 
Dynamite command line. Each line in the 
label file is of the form: 

label EQU value class 

for example; 

Init EQU $2A L 

Where Init is the label, $24 is the value 
and "L" is the class. Initially eight 
label classes are defined: see Table 2. 
These classes are sufficient for a simple 
disassembly* but I found myself defining 
additional classes very soon. A class is 
defined by putting some labels in the label 
file with that class. All the unused let- 
ters A..Z can be used as new classes. For 
example, when I disassemble modules from 
OS-9. I usually have to define labels for 
offsets in the System Direct Page, and the 
process descriptor. For the System Direct 
Page the D class is fine, but for the pro- 
cess descriptor I have td define a new 
class. I usually use P. 

Dynamite will use its default classes 
of labels wherever they are appropriate 
unless it is given instructions to use 
another class of label . A good disassem- 
bler needs to be able to assign labels to 
values very specifically. Although 8 is 
the offset of the P$User in the process 
descriptor control block, it wouldn't gen- 
erally be a good idea to assign the name 
t^S^User to the value 8 throughout a program, 
-^amite gives you two ways to limit the 
.ope in which a label is used. A class of 
abel is activated by a command of the 
form : 

<mode> <class> [<offset>] 
<range> 

The modes are listed in Table 3. The class 

is a default class, or one defined in the 

label file. The offset is added to a value 

before the proper label is looked up, then 

ncluded in the disassembly listing. This 

.Id be used to generate instructions 

- e : 

Ida #CR+$80 

in the disassembly. The range gives the 
range of offsets from the start of the mod- 
ule being disassembled over which the map- 
ping given by this command is in effect. 

Commands can come either from standard 
input after Dynamite is started, or from a 
command file. 

If the reason for disassembling a mod- 
ule is to learn how it works, the listing 
generated by Dynamite should be enough. If 
the goal is to revise the original program. 
Dynamite can generate a file which contains 
source which can be assembled with the 
Microware standard assembler, or any com- 
patible assembler to give a module identi- 
cal to the original . 

The OS-9 version of Dynamite expects to 
disassemble 6809 instructions from a file 
witn modules in OS-9 format, but there is 
an option which causes it to disassemble a 
file into 6800 instructions and another 
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option which tells it to expect to find the 
module in Motorola or FLEX format instead 
of the usual OS-9 format. 



OPERATION 

I use Dynamite to sort of chew away at the 
edges of a program until I have it reduced 
to an understandable listing. First I let 
Dynamite have its head, and produce a list- 
ing using all its defaults. Using this 
listing, I start building the labels and 
commands files. At first I just define the 
data areas and a few labels. Then I go 
through a cycle of running Dynamite then 
using the output to refine and extend the 
contents of the commands and labels files 
until the listing satisfies me. Then I ask 
Dynamite to generate a file with the source 
in it. This file is the best I can do with 
Dynamite. It isn't well formatted, and has 
no comments. The final polishing has to be 
done with an editor. 

Please realize that if you disassemble 
proprietary software (such as Dynamite 
itself) the same laws and moral obligations 
that should prevent you from passing out 
copies of the original program apply to the 
disassembled program. 



LIMITATIONS 

When I first tried to use Dynamite, I had a 
terrible time. I blamed the documentation. 
Determined not to be unfair, I sat down and 
read the manual from start to finish. 2 
won't say it was easy reading, but once I 
had chewed my way through it I underst*ood 
how to use Dynamite. The manual is a lit- 
tle brief for the manual of a program that 
does such tricky work, but it Is complete. 
It is not set up to be skipped through! 

Dynamite's advertising might lead a 
person to believe that disassembling a mod- 
ule with Dynamite is easy. You run Dyna- 
mite against a file and it falls apart into 
neat code. This is not true at al 1 . . . 
disassembling a module is hard. You have 
to figure out all the tricks the person who 
wrote the program used. This is not too 
hard to do for a short, simple program, but 
long tangled modules are much harder to 
disassemble than they are to read in com- 
mented source form, and some modules are 
hard to understand even when the original 
source is in front of you. 

It seems a little silly to design a 
disassembler with the ability to insert 
comments in its output, but Dynamite is 
such a complete product that I am a little 
disappointed that there is no way to 
include a "comment file" in the input for 
Dynamite, I understand that Computer Sys- 
tems Center is working on this shortcoming. 



SUMMARY 

I am very impressed with Dynamite. It does 
about as good a job of helping a person to 
disassemble a module as it can do. For 
example, if Dynamite finds that a label 
falls in the middle of an instruction, it 



throws in an ORG to adjust the PC so the 
label falls at the start of an instruction. 
This keeps data areas from throwing the 
disassembly out of whack; usually if there 
is a data area in a program, there is a 
reference to the first instruction after 
the data area which Dynamite can use to get 
itself lined up again if it hasn't been 
told that the data area is there and has 
gotten itself wrapped around the axle by 
trying to turn data into instructions. 

Dynamite is designed to be useful for 
several different types of disassembly. 
The quick disassembly can be done without 
building any files. The most important 



information can be supplied interactively. 
Used this way Dynamite can produce a usable 
listing in just a few minutes. The full 
power and flexibility of the program shows 
up when a higher quality listing is the 
goal. Dynamite lends itself to the process 
of successive refinements that leads to a 
clear disassembly. 

I don't recommend Dynamite for every 
OS-9 user. In fact, I imagine there are 
not many 05^9 users who have a need for 
this type of software, but for those who 
need a disassembler, Dynamite is everything 
it should be. 
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A REVIEW OF RMS 



RMS (Record Management System) is a prirtii- 
tive» but useful tool for organizing and 
processing data. It isn't a database sys- 
tem, or even a polished record management 
system, but, nevertheless, I rather like 
it . 



OVERVIEW 

RMS stores data using at least two files. 
The _rms file contains data. It must be 
formatted in advance using the RMSNEW util- 
ity. The _dic file contains a description 
of the data in the _rms file. The _dic 
file must be created with a text editor 
before any data can be placed in the ^rms 
file. A third file type _ndx (index) is 
used when a _rms file must be sorted on 
some key other than the one designated in 
the dictionary file. Many _ndx files can 
be generated, one for each ordering of the 
file. Index files can be created* with the 
INDEX utility, or any other program that 
generates a file with a key value on each 
1 ine. 

RMS has to know many things about your 
terminal before it can be used. A file 
called rms_trm must be build with a text 
editor and placed in the root directory of 
/DO, or the directory which will be the 
default data directory when RMS is run. 
The rms_trm file must contain the hexadeci- 
mal representations of 88 bytes of data 
including 31 terminal characteristics and 
command codes . 



SOME DETAILS 

RMS saves information in record groups con- 
sisting of one "primary" record and any 
number of "secondary" records related to 
the primary record. The secondary records 
aren't required, but they are important 
when a variable amount of information is to 
be associated with each primary record. 



I use primary and secondary records in 
the database of Prairie Home Companion (an 
excellent program on Public Radio each Sat- 
urday evening) programs I keep. Some 
information about each week's show fits 
nicely in the primary record: a date, and a 
comment to act as a title for that week's 
show, I maintain secondary records to save 
the names of the guests, notes on each mon- 
olog, and notes on each "advertisement." I 
use the secondary records because although 
I could probably put a ceiling on the num- 
ber of guests, monologs and adds that might 
occur in a program, the ceilings would have 
to be much higher than the usual numbers. 
RMS assumes that all fields will have data 
in them when it allocates space for a 
record; so leaving space for data that 
isn't usually needed would waste lots of 
file space. Since I only use as many sec- 
ondary records as I need, they use space 
comparatively efficiently. 

The dictionary file associated with 
each RMS file defines the structure of the 
data in the file and the way the records 
are displayed on the screen. If secondary 
records are used, the dictionary file con- 
tains the formats for primary and secondary 
records . 

The first line in the dictionary file 
contains the title for the primary records. 
This title is displayed on the screen when 
the RMS editor is being used to edit a pri- 
mary record. Lines following the title 
line are used to define fields in the 
record, one field per line. The first 
field is the "key" for the record. The key 
can be used to select records for editing 
very quickly. The line defining a field 
contains the name of the field, the length 
of the field, the type of data to be stored 
in it (alphanumeric, numeric, money, or 
date), the prompt to use in the editor, and 
various data validation options. The field 
can be made optional, a minimum length can 
be specified, and a range or list of accep- 
table values can be given. 

The dictionary file I use for my Prai- 
rie Home Companion file demonstrates some 
of the features of RMS. I include it here 
as an example. 



"P r a i 


T i 


e H 


ID e C in p 


DATE 


8 


D^ 


"Date aired:" 


COMMENT 1 


50 


A* 


"Comments: " ; 


C0MMENT2 


50 


A* 


ti n • 

1 


POINTl 


15 


A' 


"Special Notes 

9 


P0INT2 


15 


A* 


"D e t a 


i 1 


s" 




DATE 


8 


D 


"Date aired:" 


TYPE 


1 


A^ 


" Type (Sponso 
"Subject: " ; 


SUBJECT 


50 


A* 


SUBJECT2 


40 


A* 


M II T 

• 


SUBJECT3 

$ 


40 


A* 


ti M : 


Figure 8: 


C 


>aniple 


RMS Definition 



anion 



[S,P,M,0,G] 



The only fields on which I used valida- 
tion are the date fields, which RMS vali- 
dates for possible dates, and the TYPE 
field, which I only permit to take one of 
five values. RMS formats the data on the 
screen using a few simple rules. The 



fields are placed in order starting in the 
upper left corner and working left-to-right 
and top-to-bottom. RMS won't split a field 
and its prompt between two lines. It is 
possible to have some effect on the screen 
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format by adding leading blanks to prompts, 
but not much. Trying to do something radi- 
cal -- like add a blank line -- makes a 
"errible mess on the screen. 

The dollar signs mark the end of each 
record definition. 

The lengths of the primary and secon- 
dary records are 138 bytes and 139 bytes. 
I kept the lengths about the same because 
RMS allocates only one size of record. It 
must leave space for the largest possible 
record; so, when two record formats are 
used, the difference in size between the 
two records is wasted for each small record 
stored in the file. 

I used an important trick on the secon- 
dary record. Since RMS only understands 
two record formats, I used the secondary 
format for five different types of records. 
The TYPE field in a secondary record indi- 
cates the meaning of the information in the 
rest of that record. 

The RMS editor is used to add, delete, 
and update records in an RMS file. It is 
also able to search through the file either 
sequentially, or by key. 

The RMS report writer ^i s powerful, but 
not versatile. It takes as input an rms 
file, a report specification file, and 
sometimes an index file. The report speci- 
fication file is something like a program. 
^nie language used reminds me of RPG . It 
can contain commands which select or 
excluoe records. Any number of lines can 
be printed for each record selected. Spe- 
cial lines can be printed at the start of a 
report, at the end of a report, at the end 
of a group of records, and at the top of 
sach page . Page breaks happen when a page 
is full, or (optionally) after each prima- 
ry, or secondary record is processed. 
Tnere are no arithmetic commands in the 
report generator, but various accumulators 
are kept: the number of selected records, 
the number of selected groups, the number 
of selected secondary records, and totals 
and subtotals for each numeric field. 

By default reports are generated with 
records sorted in ascending order on their 
key. Other orders can be specified by 
using an index file. 

Index files can be generated by the 
.NDEX utility. INDEX produces a file that 
contains a list of record key values. If 
records are selected from the RMS file in 
the order specified in the index file they 
will be in the order specified when INDEX 
was run to create the index file. For 
example: 

INDEX phc Points Point 1 

would generate an index file called Points 
which could be used to sort the phc RMS 
file in ascending order on the POINT 1 
field. Index files can be edited to gener- 
ate order ings that are beyond INDEX'S abil- 
i t ies . 

The RMSCOPY utility can be used to copy 
RMS files, but it can also do much more. 
RMSCOPY can be used to add fields to a 
file, remove fields, or merge similar RMS 
files. 



142 OS-9 User Notes Volume I 



FLAWS 

Setting RMS up is exceptionally difficult. 
It took me hours to get the _trm file 
right. The worst part of my problem was 
that RMS didn't help me uncover problems, 
it just wouldn't work. I have a terminal 
which uses ANSI standard control sequences 
which some programs have trouble with. 
Other people might not have quite as hard a 
time as I did. 

The documentation keeps referring to 
file names with dots in them, but RMS 
always uses underscores. I called the pro- 
gram's author to ask about this. It seems 
that when RMS was written for OS-9 dots 
weren't allowed in file names. I assume 
that there is a FLEX version of RMS which 
uses dots where the manual says they should 
be. Since DS-9 now permits dots in file 
names, RMS could be adjusted to fit its 
manual, or the document could be updated to 
reflect the use of underscores. That nei- 
ther of these things has been done indi- 
cates a negligent attitude that is disturb- 
ing. 

It is practically impossible to format 
the screen any way other than the way RMS 
wants it. This would be easier to take if 
I liked the way RMS formats the screen. I 
prefer to use up the whole screen, and RMS 
packs the fields as close together as pos- 
sible. 

RMS's file structure is wasteful of 
disk space. Since it can't handle 
variable-length fields or records, it uses 
more space per record than is necessary in 
almost every case. It also has to format 
the entire file before any records can be 
placed in it. It would be more consistent 
with OS-9 conventions to start off with a 
small file and enlarge it as required. 

Index files aren't automatically updat- 
ed. That means that if you generate an 
index file, then insert or delete records 
in the _rms file, the index file is out of 
date and has to be made over again. It is 
easy to forget to make new index files, and 
RMS doesn't do anything to make it easier. 



SUMMARY 

I find RMS useful, but frustrating. It is 
not a database program; it doesn't even 
pretend to be. Before I could discover how 
useful RMS is I had to get it set up and 
got used to its limitations. These were so 
discouraging that I almost gave up on the 
program. I'm glad I didn't. I use the RMS 
editor as tool for searching quickly 
through large files, and generating reports 
on the contents of those files. I wish RMS 
could deal with multiple keys, but, for 
many applications, one key is plenty. As a 
report generator RMS is quite good, includ- 
ing all the most commonly used features. 
It would be better if there was some way to 
do arithmetic, but I'm surprised how well I 
can make do with what's there. 

I had heard that RMS was inclined to 
crash, but I haven't been able to get it to 
do anything unexpected except when I messed 
up its _trm file, or tried to get it to 
format the screen in a way contrary to its 
nature. 



RMS is not a highly polished program. gram for OS-9, but, since I probably won't 

In fact, it's primitive. Not primitive in get arounO to that, I expect that RMS win 

a sloppy sense ... more simple and rough- continue to get a moderate amount of use 

hewn ... like a well build log cabin. It around here, 
makes me want to write a real database pro- 
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RMA (Relocating Macro Assembler) and RLINK 
(Relocating Linker) are new programs from 
Microware. Tney are required for C (and 
probably for future languages from Micro- 
ware), and are currently bundled with C. 
Those who already have the C compiler from 
Microware shouldn't consider purchasing 
RMA/RLIfs(K -- they already have them under 
the names c . asm and clink. 



OVERVIEW 

It is easier to explain RLINK's purpose 
than RMA's. RLINK takes one or more files 
created by RMA and turns them into an exe- 
cutable module. RMA is a tool which makes 
writing large programs easier with a moder- 
ately good macro facility and a variety of 
tools which permit a program to be divided 
into several pieces which can be assembled 
separate! y . 

This separate assembly is the really 
important part of RMA. With separate 
assembly it is easy to build a Tibrary of 
procedures which can be called from any 
program. Structured programming requires 
that each procedure be as independent of 
other procedures as possible. It is much 
easier to do this when each module has 
clear connections to other modules -- in 
particular, any shared data should be not- 
ed; RMA makes it easy to isolate proce- 
dures, and makes it hard to hide shared 



SOME DETAILS 



RMA includes the usual conditional assembly 
statements: 



FAIL 

Generates 

message. 



an assembler error and 



IF/ELSE/ENDC 

Do just what they should, 
optional . 



ELSE is 



RBPT/ENDR 

repeats a set of statements a speci- 
fied number of ^ times. 

These statements can be used in the body of 
a program, or in macros. Macros amount to 
procedures, or specially defined instruc- 
tions which can be used very much as if 
they were 6809 instructions. A macro is 
defined by the MACRO/ENDM statements. A 
macro can be given parameters which are 
referred to within the macro by a backslash 
followed by a number: \1 would be the first 
parameter, \2 the second, etc. The number 
of parameters given is available through 
the special operator \^. and the length of 
any parameter is available through the 
operator \Ln where n is the number of the 
argument whose length is in question. 



wap MACRO 

argl — points to 
arg2 — another 1 
arg3 — the numbe 

ITNE V/ - 3 

FAIL Swap: must 

ENDC 

pshs A,B,X,Y 

leas -1,S 

leax \1,U 

leay \2,U 

ble \8Lx 
Ida B,X 
sta ,S 
Ida B,Y 
sta B.X 
Ida ,S 
sta B,y 
decb 

bne \gLp 
\@Lx leas 1,S 

puis A,B,X,Y 
ENDM 

Figure 9: RMA Macro 



\@Lp 



exchanges bytes in memory 
memory location 
ocat ion 

r of bytes to swap (a constant) 
check the number of args. 
have exactly three arguments 



Hake work space on stack 
address of first variable 
address of second variable 
number of bytes to swap 
if none; stop 



clear work space 
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When a macro needs unique labels, RMA 
offers the \^ operator. This operator 
returns an ^ fol lowed by a number unique to 
each invocation of each macro. 

A sample RMA macro can be found in Fig- 
ure 9. This macro could be invoked with 
tne statement : 

Swap Varl,Var2,20 

which could be used as many times as neces- 
sary in a program with Swap defined. 



The Separate Assembly Facility 

RMA includes statements which define three 
different "program sections." 

The PSECT section contains program code 
and constants. RMA can only deal with one 
PSECT per assembly. The PSECT statement 
includes all the data given in the MOD 
statement in ASM except the module length, 
but only the entrypoint argument to PSECT 
IS an address. The parameters are; 

• NAME 

Up to 20 byte name for the PSECT 

• TYPBLANC 

the type/ language for the PSECT 

• ATTRREV 

the attribute (ReEnt ?) and revision 
level of the PSECT 

• EDITION 

the edition number to be used for the 
executable module. 

STACKS J ZE 

The estimated size of the stack for 
this procedure. 

• ENTRY 

The Label used for the first instruc- 
tion to be executed in the PSECT. 

If the PSECT is the mainline segment of the 
program being written, all the arguments 
must have values; for example: 

PSECT Example, Prgrm+Objct, 

ReEnt+l,l,250,EntryPt 

Procedures which are used as subroutines 
must have zeros in some fields; for exam- 
ple: 

PSECT SubProc, 0,0, 0,100,0 

The PSECT section contains only con- 
stant data: instruction mnemonics, OSS, 
fee, fdb, fcs, fcD, rzb (reserve zero-value 
bytes, VSECT, ENDSECT. and END. In partic- 
ular rmb is not allowed in a PSECT. 

The VSECT section reserves memory loca- 
tions. It has two forms: 

VSECT DP 
reserves space in the direct page, and just 
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VSECT 

reserves space outside the direct page. 
The VSECTs are used for the variables that 
would normally be addressed off the U reg- 
ister in an OS-9 program. Normally only 
the rmb instruction is used in a VSECT, but 
for elaborate programs it is possible to 
have variables automatically ini tial 1 ized. 
If you are willing to include the initial- 
lization code in your program (it is 
included with RMA) you can use fee, fdb, 
fcs, fcb, and rzb in a VSECT along with 
rmb. It is important that there is no 
official way to know where variables allo- 
cated in a VSECT will be relative to other 
variables. Your program will be able to 
find its variables, but finding relation- 
ships between the addresses of variables at 
assembly time is hard. 

As many VSECTs as convenient can appear 
in a PSECT. 

If VSECT is used inside the PSECT, as 
it usually is. it will cause the linker to 
allocate space for the variables in it. If 
a VSECT is placed outside the PSECT it will 
make the variables in the VSECT known in 
the code, but not allocate any storage. 
This Is a useful trick for cases when you 
know that a block of variables has already 
been allocated and you want access to all 
of them. I haven't tried this, and I can't 
find it ir the manual. but Microware 
declares it will work. 

A CSECT is just a way to assign values 
to names. They are used extensively in the 
DEFS files for RMA. Only the rmb statement 
can be used in a CSECT. If the CSECT 
statement is given an argument, that argu- 
ment is the starting value in the CSECT, 
otherwise the values in the CSECT start at 
zero. 

Every program sector must be terminated 
with an ENDSECT . A PSECT can contain other 
sectors, but in general sectors should not 
be nested. 

A label can be made globally available 
by following it with a colon ":" when it is 
defined. If a label isn't global, it is 
only known in the PSECT where it is 
defined. If a label isn't global, it can 
be used to represent a different thing in 
each, separately assembled, file. 

Speaking of labels: RMA permits labels 
up to nine characters long and always dis- 
tinguishes upper and lower case letters. 

The files that are produced by RMA, 
called relocatable files, can be decoded by 
a program called RDUMP which is included 
with RMA. RDUMP can give anything from a 
quick summary to an exhaustive dump of 
information about symbols referenced and 
defined in the file being investigated. 



SOME INTERNALS 

Since RMA has no way of telling what off- 
sets RLINK will assign to variables defined 
in VSECTS, it is often unable to use the 
small -offset forms of the indexed instruc- 
tions. References to data in VSECTS are 
assembled as 16 bit offsets. RMA records 



information about variables defined and 
used in a PSECT which Is used by RLINK. 
RLINK goes through the files it is linking 
filling in the blanks left by RMA . 

RLINK accepts a list of files to link 
and libraries to use. It will link all the 
files on the command line even if the main- 
line PSECT doesn't reference anything in 
them. If there are any references left 
unresolved, RLINK will search the 
library(s) for the PSECTs needed to resolve 
the references. A library is simply a 
group of PSECTs merged together: the MERGE 
command does this nicely. PSECTS in a 
library can call one another, but, since 
the library is read sequentially, unre- 
solved references must be to PSECT further 
along in the file, or in another library 
which will be searched later. 



LIMITATIONS 

I haven't been able to discover aa easy 
way to have RMA calculate the length of a 
group of variables in a VSECT. The concept 
of a useful data position counter ("." in 
ASM) doesn't exist in RMA. There are sev- 
eral counters (Direct Page, Uninitialized 
data, and initial lized data), and. in any 
case, the linker has the last word on 
addresses. I got used to this problem, and 
I can't think of any way for Microware to 
design it out of RMA without introducing 
other problems, but it is a serious prob- 
lem. The lack of a "." caused other habits 
I have to generate errors as wel 1 . 

RMA's inability to determine offsets in 
a VSECT causes the 16 bit offset instruc- 
tions to be used more than they are in pro- 
grams assembled with ASM. These instruc- 
tions are relatively long and slow. At 
first this really upset me, but my experi- 
ence and Microware' s indicates that it 
isn't a significant problem. I converted 
several very large (5000 to 10000 lines of 
code) programs from ASM to RMA and they 
generally got a little smaller. Microware 
declares that they have converted BasicOS 
from ASM to RMA, and that it got a little 
smaller through the conversion. I attri- 
bute the small decrease in size to better 
coding habits that RMA encourages. Still, 
in the last analysis, programs assembled by 
ASM can be made to run faster than programs 
assembled by RMA. 

This is really nit-picking, but the 
command line option which should set the 
width of the listing which RMA can produce 
doesn't work. It's not that important, but 
little problems like that could give a less 
forgiving person than me a bad impression 
that would spoil the excellent job done on 
the really important parts of the product. 

I found several problems In the first 
copy of RMA that I got, some of them quite 
serious. I now have edition five. If you 
have an earlier edition, I would strongly 
recommend getting an update. If you mean 
to use c.asm as a stand-alone assembler, 
you should also see to it that you have an 
up-to-date revision. The problems were 
tricky things that wouldn't generally show 
up with correct code, but I haven't been 
able to uncover any bugs other than the 
problem with the width of the listing in 
the current revision of RMA 



Converting programs from the standard 
assembler to RMA is not as simple as one 
might think. To start with the standard 
DEFS files won't work, and Microware didn't 
include complete DEFS files with RMA. I 
frequently use "." ... that had to be dealt 
with, RMA can't handle as many symbols as 
the standard assembler before the symbol 
table overflows. This meant that I 
couldn't just convert a program into RMA, I 
had to use RMA. A large program MUST be 
broken down into several PSECTs and assem- 
bled in pieces then linked. 



SUMMARY 

I think RMA/RLINK is wonderful, I am a 
serious assembly language programmer. I 
write large programs that take a long time 
to assemble, and have quantities of chunks^ 
of code that I "USE" in assembler programs 
to prevent myself from having to rewrite 
commonly used procedures. RMA lets me 
build libraries, and assemble only the 
small part of a program that I change. I 
also care about structured programming, and 
RMA lets me use that discipline for assem- 
bly language programs. 

Assembly language procedures to be 
called from C must be written in RMA, and I 
have been able to call C procedures from 
RMA programs. RMA comes with the C compi- 
ler, but the documentation that is included 
in the C manual isn't sufficient to make 
full use of c.asm/c . 1 ink . The information 
I have given in this review may supplement 
the C manual enough, but, if not, I would 
recommend purchasing a copy of the 
RMA/RLINK manual from Microware. 

The standard assembler is easier to use 
for short and simple programs. RMA has a 
lot more power, and is correspondingly 
harder to use. Nevertheless, if you are 
serious about assembler, RMA/RLINK is 
important to have. Even if the added 
structure doesn't mean anything to you, the 
large amounts of time that you won't spend 
waiting for big programs to assemble will 
be worth the investment in money and time 
that RMA requires. 



Review of RMA and RLINK 147 



mSc OS-9 User Notes Volume I 



INDEX 



ACIA ... 48 

Active Process Queue ... 58 
ANSI Protocol ... 39 
Application Programs ... 35 

B-Trees . . . 131 

Basic09 ... 15. 35 

BasicOS Installation ... 77 

Binary Trees ... 131 

Boot file ... 9 

Construction ... 9 
BT9 ... 131 
Buffers ... 26 
Busy Wai t i ng ... 25 
BWord ... 60 

C Asm ... 145 

C Functions - Floating Point 

C Language ... 96, 113 

C Link . . . 145 

Cache ... 49 

Calc ... 21 

Carry Bit ... 29 

Changing Disks ... 78 

Changing I/O Configuration .. 

CharCt ... 60 

CHD ... 37 

CHX ... 37 

CIS COBOL ... 123 

Clearbrook Software Group . . . 

COBOL ... 123 

COBOL Debugger ... 124 

CoCO ... 62, 77. 81 

CoCo Disk Driver ... 87 



Commands . 


. . 9 




ATTR . . 


37 




Backup 


. . 103- 


104 


CHD . . . 


37, 103 


, 105 


CHX . . . 


37. 48, 


103, 


DCHECK 


. . 113 




DELDIR 


. . 9 




DIR . . . 


55, 103 


-104 


DSAVE . 


. 9 




EX ... 48 




Format 


. . 103 




IDENT . 


. 9 




Kill . . 


48 




LOAD . , 


78 




LOGIN . 


. 56 




MAKDIR 


- . 36 




MDIR . . 


78 




MFREE . 


. 78 




0S9GEN 


. . 9 




PRINTERR ... 9 




PWD . . . 


9 




PXD ... 


9 




Setpr . 


. 48 




TSMON . 


. 56 




UNLINK 


. . 78 




W ... 48 




CompuServe 


... 77, 


81 


Concurrency problems . . 


Busy Waiting . . 


. 25, 


Execution Sequence . 


Lockout 


... 25 





Device Descriptor ... 74 
Device Driver ... 6 

Beeper ... 82 

Logical ... 48 

Nul 1 ... 6 

Nul 1 Program ... 7 

DS-9 Service ... 26 

Service Routine ... 57 

Static Storage ... 49 
Device Drivers ... 26 
Device Independance ... 74 
Directories ... 36 

Anonymous ... 37 

Changing Disks ... 78 

CHD ... 37 

CHX ... 37 

Data Directoy ... 36 
-. 96 Default directories ... 

Dir command ... 104 

Directories as files ... 

DirSqz ... 118 

Dr ... 115 

Execution Directory ... 

Formatted 1 ist ing . 
74 Location on Disk . . 

MAKDIR ... 36 

Multiple Links to a File 

Reading Directories 

Root ... 36 
131 Updating ... 113 

DirSqz ... 118 
Disk Contention ... 26 
Dispatcher ... 57 
Dissassemblers . . . 137 
Dr ... 115 
Driver .Device ... 57 



105 



16 



57 



D-Series . , . 132 
D/A Converter (CoCo) 
Data Base . . . 141 
Data Directory ... 36 
DAttr ... 132 
DCopy ... 132 
DDel ... 132 
DDir ... 132 
Debugger ... 35 
Debugging ... 50 
Dedit ... 131 
DefsList ... 27 



25 



89 



105 



107 



. . 36 

113 
48 



107 



113 



Dri ver2 
DYNACALC 
Dynaf orm 
Dynami te 
DynaSpel 1 
DynaStar 



22 

135 

35 

137 
. 35. 

35 



96 



Edit ... 35 
Editors ... 88 
Enqueue/Dequeue ... 16 
Entry Point ... 28 
Execute Only files ... 56 
Execution Directory ... 36 
Execution file attribute .. 
Execution Sequence ... 25 



108 



File Attributes 


. . . 55 


File Descriptor 


. . . 108 


File Security . . 


. 55 


File Sharing . . , 


55 


File. Attributes 


. . . 55 


Filter ... 39 




Flex ... 95 




Frank Hogg Labs 


. . . 35 


Fujitsu ... 47 





Generic OS-9 . . . 107 
GETSTAT/PUTSTAT ... 39 
Gimix ... 47, 61 
GIMIX III ... 6 
GOTDXY ... 39 
Graphics ... 61 
Graphics hardware ... 87 

I/O Managers ... 74 

I/O redirection ... 73 
I/O System ... 73 
IFPl/ENDC ... 27 
Initial Program ... 56 
Initialization Table ... 75 
Interrupt Service Routine .. 
Interrupts ... 57. 89 



57 



Index 149 



47, 123 



u3M Group . . . 

Oohnson, Dan 



47 
(D.P. 



) 



87 



Level II Memory Requirements . 
LocKer ... 18 
Locking . . . 16-17 
Lockout ... 25 

Macros . . . 145 

Memory for Level II ... 87 

Memory Management . . . 107 

Mice ... 88 

Mix ... 25 

Module Type ... 27 

Modules ... 16 

Data Modules ... 16 

Entry Poi nt ... 28 

Locking . . . 16- 17 

Memory requirement ... 78 

Module S ize ... 17 

Module Type ... 27 

Reentrant ... 27 

Revi ST on ... 27 

Shared ... 16 

Storage Requirement ... 28 

Version Number ... 28 
MOID ... 56 

* -jI ti -Processors ... 88 
»'.. 1 1 1 tasking ... 82 
^^JMPS . . . 4"l 

'.O'^-Standard Hardware . . . 107 



Programs ... 13 
Beeper ... 84 
Beeper2 ... 90 
BWord ... 53 
Calc ... 21 
81 CharCt ... 64 

COBOL Benchmark . . . 129 
Cobol Sieve . . . 128 
Cobol Test . . . 126 
DFormat ... 112 
DirSqz ... 1 18 
DList , , . 109 
DList2 ... 1 10 
Dr ... 115 
Driver One ... 14 
Driver Two ... 22 
FRexp ... 100 
Getting a good Mix ... 25 
Grapher ... 66 
Help_B ... 45 
Id ... 111 
Locker ... 18 
Modf ... 100 
ParamMod ... 44 
POpt ... 27, 30 
Rast ... 70 
Sound ... 83 
StrtTask ... 67 
StrtTask One ... 13 
TBeep2 ... 92 
TestBeep . . 
TstSSig . . . 
Vcia ... 51 
Protect ion ... 



86 
99 

55 



C-F . . . 


121 


OFlex . 


. . 95. 


0S9P1 . 


. . 107 


0S9P3 . 


. . 97 



105 



P/V ... 16 

Parameter String terminator ... 28 

Paramod ... 42 

i-'ascal ... 5, 35-36 

Brief Review ... 35 

Microware ... 5 

Release 2.0 (Microware) ... 36 

Virtual Storage ... 5 
3SWord ... 56 
- cssword file ... 56 
^'ipes ... 59 

Algorithm Partition via ... 60 

Bug in PIPEMan ... 60 

Direct from programs ... 60 

Example of a Pipeline ... 60 

Fi 1 ters ... 59 

Internals ... 61 

Interprocess ... 62 

Overview ... 59 

Snell ... 59 

Words (Fi Iter) ... 59 
POpt ... 27 . 30 
2>orting OS-9 . . . 107 
''-r inter Options ... 27 
-Priority ... 26 
t^rivac ... 47 
Processes ... 10 

Address Space ... 12 

Background ... 48 

Busy Waiting ... 25, 57 

Concurrency problems ... 16 

Concurrent ... 15 

Execution Sequence ... 25 

Getting a good Mix ... 25 

interprocess Communication ... 15 

Lockout ... 25 

Parameter Area ... 11, 15 

Pr lor i ty ... 26 
Program length ... 27 



Rasterization ... 61 
Record Management ... 141 
Recovery ... 113 
Reentrant ... 16 , 27 
Revision ... 27 
RLINK ... 145 
RMA ... 145 
RMS ... 141 
Runs ... 60 

School ... 59 

School s ... 41 

Separate Assembly . . . 145 

Service Requests ... 10 

F$Fork ... 11 

F$Send ... 57 

Fork ... 10 

Link ... 16 

SetStat SS.SIG ... 97 
Shared modules 
Shel 1 ... 28 
SHELL Commands 
SHELL Push ... 48 
Smoke Signal Broadcasting 

101 
Sort ... 47, 60 
Sound Generation 
Spel 1 ing Checker 
Spl i t Screen . . 
Spread Sheet . . 
SS.SIG SetStat 
Stable Storage 
Standard Error 
Standard Error Path 
Standard I/O Paths . 
Standard Input ... 73 
Standard Output ... 73 
Standards ... 39, 101 
Startup Fi le ... 56, 73 
Storage Requirement . 
Suspend State ... 57 

ref id=Proces . Suspend State 
SWTPc ... 107 

Tano Dragon ... 47 
Televideo ... 97 
Terminal Commands ... 40 



16 



48 



81 
96 
49 
135 
. . 97 
. . 113 
. . 73 



. 73 
73 



28 



47. 81. 



57 



150 0S"9 User Notes Volume I 



Terminal Handling ... 123 User Seminar ... 47 

Terminal Support ... 39 Users Group ... 29, 47, 62 

Time Sharing ... 56 

Tone Generation ... 89 Vcia ... 51 

Translation Lower to Upper Case ... 28 Version Number ... 28 

Tuning ... 26 VTerm ... 49 

Uniq ... 60 Waveform ... 82 
UNIX ... 36 

USE ... 27 XOn/XOf f ... 9 
User Number ... 56 



Index 151 



1^:2 OS-9 User Notes Volume I 



